vortex-cli 6.1.0__tar.gz → 6.2.0__tar.gz

{vortex_cli-6.1.0/vortex_cli.egg-info → vortex_cli-6.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vortex_cli
-Version: 6.1.0
+Version: 6.2.0
 Summary: Vortex CLI
 Author-email: Jordan Amos <jordan.amos@gmail.com>
 License: MIT License
@@ -176,7 +176,6 @@ For a full list of commands see `--help`.
 - `schema`: Manage the Puakma data dictionary (PMATABLE/ATTRIBUTE): record table/column definitions and print the DDL to run by hand. Never executes DDL.
 - `compile` (or `build`): Compile an application's Java Design Objects into `zbin/` using the Eclipse compiler (ecj).
 - `libs`: Show or refresh the per-server Java library cache (each server's `puakma.jar` and shared libraries, downloaded from the server itself).
-- `agent`: Generate agent/editor support files (CLAUDE.md, Puakma skills, code snippets) in the workspace.
 - `docs`: Open the Tornado Server Blackbook.
 - `execute`: Execute a command on the server.
 
@@ -483,23 +482,3 @@ On a `backend = gateway` server the dictionary is reached through webdesign's vo
 the gateway's `dictionary` endpoint (`GatewayDBRead` to read, `GatewayDBWrite` to change).
 That API cannot record `--default` or `--position` (refused) nor the column half of `--ref`
 (warned) - see [SOAP-free on backend = gateway](#soap-free-on-backend--gateway).
-
-### Agent Support Files
-
-`vortex agent` copies bundled support files into the workspace `.vscode` directory so they are
-included in the generated code-workspace: an `AGENTS.md` with Puakma ground rules for coding
-agents (including pointers to the bundled Blackbook v2 architecture reference), a `CLAUDE.md`
-that points Claude Code at `AGENTS.md`, a `.claude/skills/` library covering Puakma development
-and the vortex workflow, and a `vortex.code-snippets` file with common Puakma Java/HTML
-snippets. Existing files are never overwritten, so they are safe to customise. These files are
-also generated automatically on `vortex --init` and before `vortex code` opens the workspace.
-
-The guidance is backend-aware: on a `backend = gateway` server the skills teach the explicit
-`vortex compile` + `vortex push` deploy loop (journaled, `undo`-recoverable, no workspace lock),
-and the `vortex watch` save-to-deploy loop is scoped to `backend = soap`. Because existing files
-are never overwritten, workspaces generated before 6.0.0 keep their old watch-centric copies -
-delete a file (or the `.claude/skills` directory) and re-run `vortex agent` to pick up the
-current version.
-
-Workspaces created before AGENTS.md existed keep their full `CLAUDE.md` (existing files are
-never touched); the new `AGENTS.md` is simply added alongside it.

{vortex_cli-6.1.0 → vortex_cli-6.2.0}/README.md

@@ -132,7 +132,6 @@ For a full list of commands see `--help`.
 - `schema`: Manage the Puakma data dictionary (PMATABLE/ATTRIBUTE): record table/column definitions and print the DDL to run by hand. Never executes DDL.
 - `compile` (or `build`): Compile an application's Java Design Objects into `zbin/` using the Eclipse compiler (ecj).
 - `libs`: Show or refresh the per-server Java library cache (each server's `puakma.jar` and shared libraries, downloaded from the server itself).
-- `agent`: Generate agent/editor support files (CLAUDE.md, Puakma skills, code snippets) in the workspace.
 - `docs`: Open the Tornado Server Blackbook.
 - `execute`: Execute a command on the server.
 
@@ -439,23 +438,3 @@ On a `backend = gateway` server the dictionary is reached through webdesign's vo
 the gateway's `dictionary` endpoint (`GatewayDBRead` to read, `GatewayDBWrite` to change).
 That API cannot record `--default` or `--position` (refused) nor the column half of `--ref`
 (warned) - see [SOAP-free on backend = gateway](#soap-free-on-backend--gateway).
-
-### Agent Support Files
-
-`vortex agent` copies bundled support files into the workspace `.vscode` directory so they are
-included in the generated code-workspace: an `AGENTS.md` with Puakma ground rules for coding
-agents (including pointers to the bundled Blackbook v2 architecture reference), a `CLAUDE.md`
-that points Claude Code at `AGENTS.md`, a `.claude/skills/` library covering Puakma development
-and the vortex workflow, and a `vortex.code-snippets` file with common Puakma Java/HTML
-snippets. Existing files are never overwritten, so they are safe to customise. These files are
-also generated automatically on `vortex --init` and before `vortex code` opens the workspace.
-
-The guidance is backend-aware: on a `backend = gateway` server the skills teach the explicit
-`vortex compile` + `vortex push` deploy loop (journaled, `undo`-recoverable, no workspace lock),
-and the `vortex watch` save-to-deploy loop is scoped to `backend = soap`. Because existing files
-are never overwritten, workspaces generated before 6.0.0 keep their old watch-centric copies -
-delete a file (or the `.claude/skills` directory) and re-run `vortex agent` to pick up the
-current version.
-
-Workspaces created before AGENTS.md existed keep their full `CLAUDE.md` (existing files are
-never touched); the new `AGENTS.md` is simply added alongside it.

{vortex_cli-6.1.0 → vortex_cli-6.2.0}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "vortex_cli"
-version = "6.1.0"
+version = "6.2.0"
 description = "Vortex CLI"
 requires-python = ">=3.10"
 readme = { file = "README.md", content-type = "text/markdown" }
@@ -41,8 +41,6 @@ vortex = [
     "docs/Blackbook v2.md",
     "docs/index.html",
     "docs/marked.min.js",
-    "templates/agent/*",
-    "templates/agent/skills/*/*",
 ]
 
 [tool.mypy]

{vortex_cli-6.1.0 → vortex_cli-6.2.0}/vortex/cli.py

@@ -1199,17 +1199,6 @@ def add_compile_parser(command_parser: _SubParsersAction[ArgumentParser]) -> Non
     _add_server_option(compile_parser)
 
 
-def add_agent_parser(command_parser: _SubParsersAction[ArgumentParser]) -> None:
-    command_parser.add_parser(
-        "agent",
-        help=(
-            "Generate agent/editor support files in the workspace "
-            "(AGENTS.md + CLAUDE.md pointer, Puakma skills, code snippets). "
-            "Existing files are never overwritten"
-        ),
-    )
-
-
 def add_execute_parser(command_parser: _SubParsersAction[ArgumentParser]) -> None:
     execute_parser = command_parser.add_parser(
         "execute",

{vortex_cli-6.1.0 → vortex_cli-6.2.0}/vortex/main.py

@@ -14,7 +14,6 @@ from vortex import util
 from vortex.colour import Colour
 from vortex.commands.agenda import agenda
 from vortex.commands.agenda import server_config
-from vortex.commands.agent import agent
 from vortex.commands.clean import clean
 from vortex.commands.clone import clone
 from vortex.commands.code import code
@@ -248,7 +247,6 @@ def main(argv: Sequence[str] | None = None) -> int:
     cli.add_render_parser(command_parser)
     cli.add_watch_parser(command_parser)
     cli.add_docs_parser(command_parser)
-    cli.add_agent_parser(command_parser)
     cli.add_compile_parser(command_parser)
     cli.add_schema_parser(command_parser)
     cli.add_execute_parser(command_parser)
@@ -291,12 +289,7 @@ def main(argv: Sequence[str] | None = None) -> int:
                 code_parser.print_help()
                 util.print_row_break()
                 remaining_args.insert(0, "--help")
-            # Ensure the agent/editor support files are mounted in the
-            # code-workspace before VS Code opens (never overwrites)
-            workspace.init_agent_files()
             return code(workspace, remaining_args, server_name)
-        elif args.command == "agent":
-            return agent(workspace)
         elif args.command == "docs":
             return docs(args.serve, args.port)
         elif args.command == "use":

{vortex_cli-6.1.0 → vortex_cli-6.2.0}/vortex/workspace.py

@@ -186,8 +186,6 @@ class Workspace:
         if not self.code_workspace_file.exists():
             self.update_vscode_settings(reset=True)
 
-        self.init_agent_files()
-
         logger.info(f"Initialised workspace {self.path}")
 
     @property
@@ -570,51 +568,6 @@ class Workspace:
         except (configparser.Error, ValueError) as e:
             _error(f"Error reading server from config: {str(e)}")
 
-    # Claude Code reads CLAUDE.md rather than the agent-standard AGENTS.md.
-    # A pointer file keeps both tool families on the same instructions
-    CLAUDE_MD_POINTER = (
-        "The workspace instructions for coding agents live in @AGENTS.md - "
-        "follow that file.\n"
-    )
-
-    def init_agent_files(self) -> tuple[list[Path], list[Path]]:
-        """
-        Copies the bundled agent/editor support files into the .vscode
-        directory: AGENTS.md (plus a CLAUDE.md pointing at it), the Puakma
-        .claude/skills library, and the vortex.code-snippets file
-        (folder-scoped, so VS Code picks it up via the .vscode workspace
-        folder). Existing files are NEVER overwritten.
-        Returns (written, skipped) paths.
-        """
-        template_dir = Path(__file__).parent / "templates" / "agent"
-        written: list[Path] = []
-        skipped: list[Path] = []
-        for src in sorted(template_dir.rglob("*")):
-            if not src.is_file():
-                continue
-            rel = src.relative_to(template_dir)
-            if rel.parts[0] == "skills":
-                dest = self.vscode_dir / ".claude" / rel
-            elif src.suffix == ".code-snippets":
-                dest = self.vscode_dir / rel
-            else:
-                dest = self.vscode_dir / rel
-            if dest.exists():
-                skipped.append(dest)
-                continue
-            dest.parent.mkdir(parents=True, exist_ok=True)
-            shutil.copyfile(src, dest)
-            written.append(dest)
-
-        claude_md = self.vscode_dir / "CLAUDE.md"
-        if claude_md.exists():
-            skipped.append(claude_md)
-        else:
-            claude_md.parent.mkdir(parents=True, exist_ok=True)
-            claude_md.write_text(self.CLAUDE_MD_POINTER)
-            written.append(claude_md)
-        return written, skipped
-
     @staticmethod
     def app_folder_name(app: PuakmaApplication) -> str:
         """

{vortex_cli-6.1.0 → vortex_cli-6.2.0/vortex_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vortex_cli
-Version: 6.1.0
+Version: 6.2.0
 Summary: Vortex CLI
 Author-email: Jordan Amos <jordan.amos@gmail.com>
 License: MIT License
@@ -176,7 +176,6 @@ For a full list of commands see `--help`.
 - `schema`: Manage the Puakma data dictionary (PMATABLE/ATTRIBUTE): record table/column definitions and print the DDL to run by hand. Never executes DDL.
 - `compile` (or `build`): Compile an application's Java Design Objects into `zbin/` using the Eclipse compiler (ecj).
 - `libs`: Show or refresh the per-server Java library cache (each server's `puakma.jar` and shared libraries, downloaded from the server itself).
-- `agent`: Generate agent/editor support files (CLAUDE.md, Puakma skills, code snippets) in the workspace.
 - `docs`: Open the Tornado Server Blackbook.
 - `execute`: Execute a command on the server.
 
@@ -483,23 +482,3 @@ On a `backend = gateway` server the dictionary is reached through webdesign's vo
 the gateway's `dictionary` endpoint (`GatewayDBRead` to read, `GatewayDBWrite` to change).
 That API cannot record `--default` or `--position` (refused) nor the column half of `--ref`
 (warned) - see [SOAP-free on backend = gateway](#soap-free-on-backend--gateway).
-
-### Agent Support Files
-
-`vortex agent` copies bundled support files into the workspace `.vscode` directory so they are
-included in the generated code-workspace: an `AGENTS.md` with Puakma ground rules for coding
-agents (including pointers to the bundled Blackbook v2 architecture reference), a `CLAUDE.md`
-that points Claude Code at `AGENTS.md`, a `.claude/skills/` library covering Puakma development
-and the vortex workflow, and a `vortex.code-snippets` file with common Puakma Java/HTML
-snippets. Existing files are never overwritten, so they are safe to customise. These files are
-also generated automatically on `vortex --init` and before `vortex code` opens the workspace.
-
-The guidance is backend-aware: on a `backend = gateway` server the skills teach the explicit
-`vortex compile` + `vortex push` deploy loop (journaled, `undo`-recoverable, no workspace lock),
-and the `vortex watch` save-to-deploy loop is scoped to `backend = soap`. Because existing files
-are never overwritten, workspaces generated before 6.0.0 keep their old watch-centric copies -
-delete a file (or the `.claude/skills` directory) and re-run `vortex agent` to pick up the
-current version.
-
-Workspaces created before AGENTS.md existed keep their full `CLAUDE.md` (existing files are
-never touched); the new `AGENTS.md` is simply added alongside it.

{vortex_cli-6.1.0 → vortex_cli-6.2.0}/vortex_cli.egg-info/SOURCES.txt

@@ -18,7 +18,6 @@ vortex/webdesign.py
 vortex/workspace.py
 vortex/commands/__init__.py
 vortex/commands/agenda.py
-vortex/commands/agent.py
 vortex/commands/clean.py
 vortex/commands/clone.py
 vortex/commands/code.py
@@ -50,12 +49,6 @@ vortex/docs/Blackbook.pdf
 vortex/docs/index.html
 vortex/docs/marked.min.js
 vortex/lib/puakma-6.0.40.jar
-vortex/templates/agent/AGENTS.md
-vortex/templates/agent/vortex.code-snippets
-vortex/templates/agent/skills/puakma-database/SKILL.md
-vortex/templates/agent/skills/puakma-design-elements/SKILL.md
-vortex/templates/agent/skills/puakma-overview/SKILL.md
-vortex/templates/agent/skills/vortex-workflow/SKILL.md
 vortex_cli.egg-info/PKG-INFO
 vortex_cli.egg-info/SOURCES.txt
 vortex_cli.egg-info/dependency_links.txt

vortex_cli-6.1.0/vortex/commands/agent.py

@@ -1,27 +0,0 @@
-from __future__ import annotations
-
-import logging
-
-from vortex.workspace import Workspace
-
-logger = logging.getLogger("vortex")
-
-
-def agent(workspace: Workspace) -> int:
-    """
-    Generates the agent/editor support files (AGENTS.md with a CLAUDE.md
-    pointer, Puakma skills, code snippets) in the workspace .vscode
-    directory. Existing files are never overwritten.
-    """
-    written, skipped = workspace.init_agent_files()
-    for path in written:
-        logger.info(f"Created '{path}'")
-    for path in skipped:
-        logger.debug(f"Skipped existing '{path}'")
-    if not written:
-        logger.info(f"All {len(skipped)} agent file(s) already exist. Nothing to do.")
-    else:
-        logger.info(
-            f"Created {len(written)} file(s), kept {len(skipped)} existing file(s)."
-        )
-    return 0

vortex_cli-6.1.0/vortex/templates/agent/AGENTS.md

@@ -1,100 +0,0 @@
-# Puakma / vortex workspace
-
-This is a **vortex-cli workspace**: Puakma Tornado applications cloned from a live server into
-`$VORTEX_HOME` as `{host}/{group}/{app}/` folders, edited locally and synced back with the
-`vortex` CLI. There is **no git, no Maven/Gradle, no test framework** inside app folders - do not
-look for them and do not scaffold them.
-
-A skill library exists in `.claude/skills/`. **Load `puakma-overview` before doing anything
-else** - it explains the Puakma mental model and routes to the specialist skills
-(design elements, database, vortex workflow).
-
-**Check every cloned app for its own documentation.** An app's `DOCUMENTATION/` design folder may
-contain an `AGENTS.md`/`CLAUDE.md`, architecture notes, or run-books specific to that app - read
-them before editing that app. App-specific instructions override the general rules here.
-
-## Non-negotiable rules
-
-1. **The server executes compiled bytes, not source.** A saved `.java` changes nothing on the
-   server until BOTH halves ship: the source, and the `.class` the local Java build produces in
-   `zbin/`. Two deploy paths exist - `vortex push <APP_ID>`, which uploads both halves in one
-   explicit step, and `vortex watch`, which uploads each on save. Which one applies depends on
-   the server's backend (see "Deploying a change" below). If the local build fails, the server
-   keeps running old bytecode with new source attached - silent drift. Wait for a clean build
-   and the `Upload DATA ...: OK` line.
-2. **No nested/inner/anonymous classes (and no lambdas) in design-element Java.** The server
-   packages one class per design element; `Outer$Inner.class` never ships - it compiles locally
-   and fails on the server. Use `Object[]` tuples or separate top-level SHARED_CODE classes.
-3. **Deploying is a deliberate step - never assume a watcher is running.** On a gateway
-   server nothing reaches the server until you run `vortex push`; a saved file is a local
-   file. On a SOAP server where the user is running `vortex watch`, the opposite holds - every
-   save while it runs IS a live deployment, across apps from ALL configured servers at once,
-   routed to the server each app was cloned from (upload lines are prefixed `[server]`).
-   Establish which situation you are in before editing, and confirm with the user before any
-   deliberate deploy step.
-4. **Never print credentials.** `config/servers.ini` may hold plaintext server passwords
-   (they can also live in the OS keyring or env vars) and every `.pma` manifest is a pickle
-   embedding DB connection credentials - never `cat` either, never paste their contents.
-5. **Production safety.** NEVER run any vortex command against a production server without
-   explicit user permission for that specific command - including read-only ones. Production
-   definitions should carry `protected = true` in servers.ini: writes then require the server
-   name typed back (`--yes` does not bypass it) and watch skips them unless
-   `--include-protected` - treat that as a backstop, not permission. Prefer one-off
-   `-s <prod-server>` over `vortex use <prod-server>` (which persists); treat any prod clone
-   directory as read-only outside a deliberate, confirmed promotion.
-6. **`vortex clean` and `vortex delete` have no undo.** There is no git to recover from.
-
-## Deploying a change
-
-Check the server's backend before deploying - it decides which path works:
-
-```bash
-vortex config --check-gateway -s <server>
-```
-
-That reports the configured backend, the negotiation result, the resolved identity and which
-`Gateway*` roles it holds. `backend` is an explicit per-server setting with no auto mode: a
-gateway refusal or outage is an error, never a silent fallback to SOAP.
-
-- **`backend = gateway`** (the recommended setup): `vortex compile <APP_ID>` and require a clean
-  build, then `vortex push <APP_ID>` - or `vortex push <APP_ID> -n <NAME>` for a single
-  element.
-  `vortex watch`'s upload path runs over SOAP/webdesign, which a least-privilege gateway
-  identity has no access to, so watch cannot deploy on such a server.
-- **`backend = soap`**: the `vortex watch` save-to-deploy loop remains correct - start it,
-  edit, and watch for the `Upload SOURCE ...: OK` / `Upload DATA ...: OK` pair.
-
-On a gateway server prefer `push` even for a privileged identity: it is explicit rather than
-incidental, journalled server-side so `vortex undo` can restore the previous version, ships
-source and compiled class together, and takes no workspace-wide lock - which is why the
-"stop `vortex watch` first" preamble attached to other commands does not apply to it.
-
-Full loop, refusals and the two paths that are still SOAP-only: `.claude/skills/vortex-workflow`.
-
-## Quick reference
-
-- Deploy loops (push and watch), servers, creating elements, undo, prod promotion:
-  `.claude/skills/vortex-workflow`
-- ACTION/PAGE/RESOURCE conventions and `<P@ ... @P>` merge tags: `.claude/skills/puakma-design-elements`
-- TableManager vs raw JDBC, SQL escaping, connection release: `.claude/skills/puakma-database`
-- Canonical code patterns: `.vscode/vortex.code-snippets` holds vetted scaffolds for
-  Open/Save/AJAX/Scheduled actions, TableManager and JDBC access, JSON responses,
-  logging, `<P@ ... @P>` page tags and AJAX JavaScript. When writing a new design
-  element or unsure of the idiomatic shape, start from the matching snippet body
-  (`pOpen`, `pSave`, `pAjax`, `pTMsave`, `pJDBC`, ...) instead of inventing a pattern.
-- Verify changes by tailing the server log: `vortex log -n 20 -k`
-
-## Architecture reference: the Blackbook v2
-
-For server architecture, request lifecycle, the Puakma API surface, addins/tasks,
-security model and anything not covered by the skills, consult the **Tornado Server
-Blackbook v2** - it is the authoritative architecture reference and is bundled with
-vortex:
-
-- `docs/Blackbook v2.md` - markdown, readable/searchable directly (the `docs` folder
-  is mounted in the code-workspace)
-- `vortex docs --serve` - serves it as a searchable local website
-- `vortex docs` - opens the original Blackbook PDF
-
-Prefer the Blackbook v2 markdown when answering architecture questions or designing
-non-trivial features rather than guessing from code alone.

vortex_cli-6.1.0/vortex/templates/agent/skills/puakma-database/SKILL.md

@@ -1,108 +0,0 @@
----
-name: puakma-database
-description: Data access in Puakma apps - TableManager for writes, raw JDBC for reads, SQL string
-  escaping, connection pool discipline, and the strict no-DDL rule. Use when writing or debugging
-  SQL or JDBC in a design element, choosing between TableManager and raw JDBC, diagnosing a
-  connection-pool leak or a server hang, or when asked to add a table/column/index.
----
-
-# Puakma database access
-
-Puakma apps use string-built SQL over server-pooled JDBC connections. There is no ORM, no
-migration framework, and typically no transactions - follow the app's existing patterns.
-
-## STRICT RULES
-
-- **NEVER create, alter, or drop tables, columns, or indexes - no DDL, ever.** Not through
-  `vortex db`, not through code, not through TableManager. Schema changes are designed as SQL,
-  written into the app's changelog/run-book (check its `DOCUMENTATION/` folder), and run BY THE
-  USER by hand. If a task needs a schema change, write the SQL for the user and stop.
-- **`vortex db` requires explicit user permission every time - no exceptions.** That includes
-  `--list`, `--schema`, and read-only SELECTs. Ask, show the exact command and SQL, and wait
-  for a clear yes before running it. `--update` (INSERT/UPDATE/DELETE) additionally requires
-  approval per statement, and on servers marked `protected = true` vortex itself will demand
-  the server name typed back - that backstop is not a substitute for asking.
-- **Writes from code go through `TableManager`** (`setField`/`insertRow`/`updateRow`), never raw
-  `executeUpdate`. Reads may use raw JDBC.
-- **Raw JDBC must release everything in `finally`**: `Util.closeJDBC(rs)`,
-  `Util.closeJDBC(stmt)`, `pSession.releaseDataConnection(cx)`. Connections are server-pooled;
-  one missed release leaks a pooled connection per request until the whole server hangs. Never
-  `return` before the `finally`.
-- **Escape every string; parse every number.** Use the app's SQL-escape helper (commonly an
-  `escapeSQL` in a shared class - it doubles `'` but does not add the surrounding quotes) for
-  any string that reaches SQL; parse numerics to `long`/`double` before concatenation.
-  Unescaped concatenation is an injection.
-- **Don't add transactions** unless the app already uses them. Existing apps follow
-  check-then-write and idempotent-upsert styles; imitate them.
-- **Never hardcode connection names or table names** when the app defines constants for them -
-  look for `CONNECTION_NAME` / `TABLE_NAME` / `PK` style constants in SHARED_CODE.
-
-## Pattern 1 - TableManager (single-row CRUD)
-
-`puakma.addin.http.document.TableManager` acquires and releases its own connection - no
-try/finally needed at call sites.
-
-```java
-// Insert
-TableManager t = new TableManager(pSession, CONNECTION_NAME, "my_table");
-t.setField("name", sName);          // strings are escaped by TableManager
-t.setField("created", new Date());
-if (t.insertRow("my_table_id")) {
-    long lNewID = t.getLastInsertID();
-} else {
-    pSession.getSystemContext().doError("Insert failed: " + t.getLastError(), this);
-}
-
-// Update - always scope user-owned rows by the owner id, even with a PK match
-t.setField("value", sValue);
-t.updateRow("WHERE my_table_id = " + lID + " AND user_id = " + lUserID);
-
-// Quick single-row read / form prefill
-TableManager tm = new TableManager(pSession, CONNECTION_NAME, "");
-tm.populateDocument("SELECT * FROM my_table WHERE my_table_id = " + lID);
-String s = tm.getFieldString("name");
-```
-
-## Pattern 2 - raw JDBC (reads, multi-row)
-
-```java
-Connection cx = null;
-Statement stmt = null;
-ResultSet rs = null;
-try {
-    cx = pSession.getDataConnection(CONNECTION_NAME);
-    stmt = cx.createStatement();
-    rs = stmt.executeQuery(sSQL);
-    while (rs.next()) {
-        // ...
-    }
-} catch (Exception e) {
-    pSystem.doError(e.toString(), this);
-} finally {
-    Util.closeJDBC(rs);
-    Util.closeJDBC(stmt);
-    pSession.releaseDataConnection(cx);
-}
-```
-
-## Performance cautions
-
-- Avoid `LIKE '%...%'` scans on large tables in hot paths (request handlers, polling ajax) -
-  they have caused production pool-starvation outages. Prefer indexed equality/prefix filters.
-- Avoid N+1 query loops in request handlers; batch with `IN (...)` or a join.
-- Every request handler shares one connection pool - a slow query under load stalls the server.
-
-## Inspecting schema (read-only, ONLY with explicit user permission)
-
-- `vortex db <dbname> --list` - tables in a database.
-- `vortex db <dbname> --schema <table>` - columns, PKs, references.
-- `vortex db <conn-id> --sql "SELECT ..."` - vortex appends a LIMIT if the query has none.
-
-## Planning schema changes: vortex schema (dictionary only, never DDL)
-
-`vortex schema <dbname> --add-table/--add-column/--update-column/--ddl ...` records
-design-time table/column definitions in Puakma's data dictionary (PMATABLE/ATTRIBUTE) and
-prints the matching DDL for the USER to run by hand - it never executes DDL itself, and
-`vortex db --schema` reads this dictionary, so keeping it current keeps schema inspection
-accurate. It still writes to the live server's system database, so like `vortex db` it
-requires explicit user permission every time.

vortex_cli-6.1.0/vortex/templates/agent/skills/puakma-design-elements/SKILL.md

@@ -1,112 +0,0 @@
----
-name: puakma-design-elements
-description: Writing Puakma design elements - ACTION Java classes (the ActionRunner execute()
-  contract, Open*/Save*/ajax* conventions, reading requests, writing responses), PAGE templates
-  (<P@ ... @P> merge tags, ParentPage/OpenAction/SaveAction design params), RESOURCEs, and
-  SCHEDULED_ACTIONs. Use when adding or editing an endpoint, page, script/stylesheet, or
-  background job, when a page renders blank, a merge tag renders empty or literal, or an endpoint
-  answers "Action Done:" (either a handler that wrote nothing, or a stale compiled class).
----
-
-# Puakma design elements
-
-## ACTION classes
-
-Every HTTP endpoint is a default-package Java class in `ACTION/` extending
-`puakma.system.ActionRunner`. Inherited fields: `pSession` (`HTTPSessionContext`), `pSystem`
-(`SystemContext`), `ActionDocument` (`HTMLDocument` - the request/response document). Override
-`public String execute()`.
-
-| `execute()` returns | Effect |
-|---|---|
-| `""` | Normal flow: OpenAction -> page merges and renders; SaveAction -> page redisplays |
-| non-empty string | Redirect (relative page name or full URL) |
-| `""` after `write()`/`setBuffer()` | The buffer is the whole response; page merge is skipped |
-| `""` after `streamToClient()` | Raw bytes already sent |
-
-If a directly-invoked action (`?OpenAction`) writes nothing and returns `""`, the server answers
-`Action Done: <date>` - that body means the handler forgot to write.
-
-`Action Done:` has a second cause worth knowing: if the *source* clearly writes a response, the
-endpoint answers `Action Done:` anyway, other endpoints on the same app answer correctly and the
-server log shows no exception, the server is running a **stale compiled class** for that element
-- not a client bug and not an auth problem. Recompile and upload it (`vortex compile <APP_ID>`
-then `vortex push <APP_ID> -n <NAME>`); the fix often needs no source change at all. Any session
-that compiles locally without uploading leaves this trap behind.
-
-**Naming conventions**: `Open<Page>` = page OpenAction; `Save<Page>` = page SaveAction;
-`ajax<Area>` = POST endpoint dispatched on an `action` form item; lower-case names = direct
-utility endpoints. Class name == design element name.
-
-**Reading the request**: query string via `ActionDocument.getParameter(name)` /
-`getParameterInteger`; POSTed form fields become document items -
-`getItemValue/getItemIntegerValue/getItemNumericValue/getItemBooleanValue/getItemDateValue`;
-HTTP metadata items are `@`-prefixed (`@Peer-IP`); server keywords via
-`pSession.getKeywordValue(name)`.
-
-**Writing the response**: `ActionDocument.setItemValue(name, value)` fills `<P@ ... @P>` tags;
-`setItemChoices(name, choices)` fills lists (`"Display|value"` strings); `write(String)` appends
-to the buffer; `setBuffer(byte[])` replaces it; `setContentType(...)` sets the type. Extra
-headers: `ActionDocument.setExtraHeaderValue(name, value, true)`.
-
-**Logging**: `pSystem.doInformation(msg, this)` / `doError` / `doDebug(0, msg, this)` - pass
-`this` so log lines carry the action name. Stack traces: `Util.logStackTrace(e, pSystem, 999)`.
-House style is catch-all `catch (Exception e)` + log + degrade gracefully.
-
-**Common ajax contract**: many apps treat a response body starting `"ERROR:"` as failure and an
-empty body as an error too - success paths should `write("OK")` or a payload. Check the app's
-JS helpers before inventing a new contract.
-
-## PAGE templates
-
-A PAGE is an HTML **fragment** merged into a parent layout, substituting `<P@ ... @P>` tags from
-document items set by its OpenAction. The wiring lives in server-side **design params**, not the
-markup: `OpenAction` (runs before render), `SaveAction` (runs on `?SavePage` POST), `ParentPage`
-(layout receiving the fragment), `AnonymousAccess=1` (no login required).
-
-- Inspect wiring with `vortex find <name> --show-params` - never guess from markup.
-- Common merge tags: `<P@Computed name="x" @P>` (server-set HTML/text), `<P@Page name @P>`
-  (include another page), `<P@ChildPage @P>` (layout slot), `<P@Text/Hidden/TextArea/Checkbox/
-  List ... @P>` (form inputs that round-trip via document items), `<P@HideStart/HideEnd
-  name="HideWhenX" @P>` (blocks stripped when the boolean item is true), `<P@Form @P>`,
-  `<P@Path @P>`.
-- URLs: `page` or `page?OpenPage` renders; `action?OpenAction` runs an action directly;
-  `page?SavePage` posts to the page's SaveAction.
-- A blank page usually means a leftover `write()` in the OpenAction or a pre-action chain.
-- An empty `<P@Computed>` spot means an item-name mismatch with the `setItemValue` call.
-- Apps often run a global pre-action (security/gating) before every request, named in
-  app-level params invisible in the clone - unexpected redirects usually come from there.
-
-## RESOURCEs
-
-JS/CSS/images served to the browser. Locally the files carry a double extension
-(`app_v1.js.js`) - reference them by design-element name (`app_v1.js`), never the local
-filename. Many apps version resources by filename (`_v1.28`) for cache busting: adding a
-version means creating a new element and updating the includes, not editing in place.
-
-## SCHEDULED_ACTIONs
-
-Background jobs extending `ActionRunner`, same `execute()` contract, run by the server's agenda
-scheduler - the **schedule lives server-side**, not in the clone. Conventions: log start/finish
-with `pSystem.doInformation`; long loops should check `shouldQuit()` and exit cleanly; design
-jobs to be rerun-safe (they will be force-run during debugging: `vortex execute --run` runs the
-job FOR REAL). View schedules with `vortex agenda` (decoded schedule, last and next run,
-overdue flag - gateway only) or `vortex execute --schedule` via the console.
-
-## New-element checklist
-
-1. `vortex new object -t <type> --app-id <APP_ID> -n <Name>`. Pages: wire
-   `--parent-page/--open-action/--save-action` at creation. `new` takes the app's lock, so if a
-   `vortex watch` is watching that app it fails with `WorkspaceInUseError` - stop that watch,
-   create, restart it.
-2. Write the code, starting from the matching scaffold in `.vscode/vortex.code-snippets`
-   (`pOpen`, `pSave`, `pAjax`, `pScheduled`, ...) when one exists.
-3. Deploy it - a new local file leaves the server-side element empty until something uploads it.
-   On `backend = gateway`: `vortex compile <APP_ID>` for a clean build, then
-   `vortex push <APP_ID>` (both SOURCE and the compiled class ship in that one step). On
-   `backend = soap`: save under a running `vortex watch` and wait for both `Upload ...: OK`
-   lines. See vortex-workflow for the full loop.
-4. Consider gating: does the app have a global security pre-action, premium/admin arrays, or an
-   `AnonymousAccess` requirement? Check the app's DOCUMENTATION and existing similar elements.
-5. Verify by exercising the URL while tailing `vortex log -k`, or render the page server-side
-   with `vortex render <APP> <PAGE>`.