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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vortex_cli
-Version: 6.1.0
+Version: 6.2.1
 Summary: Vortex CLI
 Author-email: Jordan Amos <jordan.amos@gmail.com>
 License: MIT License
@@ -35,9 +35,9 @@ Classifier: Programming Language :: Python :: 3 :: Only
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: httpx==0.24.1
-Requires-Dist: tabulate==0.9.0
-Requires-Dist: watchfiles==0.19.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: tabulate>=0.9
+Requires-Dist: watchfiles>=0.19
 Provides-Extra: keyring
 Requires-Dist: keyring; extra == "keyring"
 Dynamic: license-file
@@ -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.1}/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.1}/pyproject.toml

@@ -5,16 +5,21 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "vortex_cli"
-version = "6.1.0"
+version = "6.2.1"
 description = "Vortex CLI"
 requires-python = ">=3.10"
 readme = { file = "README.md", content-type = "text/markdown" }
 license = { file = "LICENSE" }
 keywords = ["vortex", "cli", "puakma", "tornado"]
 dependencies = [
-    "httpx==0.24.1",
-    "tabulate==0.9.0",
-    "watchfiles==0.19.0"
+    # httpx must stay >=0.27: 0.24.x pulls httpcore 0.17.x, whose
+    # _backends/anyio.py does `anyio.abc.ByteStream` at class-definition time.
+    # anyio 4.15.0 made `anyio.abc` a lazy submodule, so that import raises
+    # `AttributeError: module 'anyio' has no attribute 'abc'` and every vortex
+    # command dies before main() runs. Pinning anyio would only defer it.
+    "httpx>=0.27",
+    "tabulate>=0.9",
+    "watchfiles>=0.19"
 ]
 authors = [
     { name = "Jordan Amos", email = "jordan.amos@gmail.com" }
@@ -41,8 +46,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.1}/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.1}/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.1}/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.1/vortex_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vortex_cli
-Version: 6.1.0
+Version: 6.2.1
 Summary: Vortex CLI
 Author-email: Jordan Amos <jordan.amos@gmail.com>
 License: MIT License
@@ -35,9 +35,9 @@ Classifier: Programming Language :: Python :: 3 :: Only
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: httpx==0.24.1
-Requires-Dist: tabulate==0.9.0
-Requires-Dist: watchfiles==0.19.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: tabulate>=0.9
+Requires-Dist: watchfiles>=0.19
 Provides-Extra: keyring
 Requires-Dist: keyring; extra == "keyring"
 Dynamic: license-file
@@ -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.1}/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.2.1/vortex_cli.egg-info/requires.txt

@@ -0,0 +1,6 @@
+httpx>=0.27
+tabulate>=0.9
+watchfiles>=0.19
+
+[keyring]
+keyring

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.