pythia-plsql 0.1.0__py3-none-any.whl

pythia_skills/plsql-explore/reference/data-dictionary.md

@@ -0,0 +1,61 @@
+# Data dictionary reference
+
+Which Oracle views back each pythia command, and what to know when going
+beyond them with `pythia sql`.
+
+## Views behind the commands
+
+| Question | View(s) | pythia command |
+|---|---|---|
+| What objects exist, status, last change | `ALL_OBJECTS` | `ls`, `invalid`, `similar` |
+| PL/SQL source, line-exact | `ALL_SOURCE` | `src`, and the apply snapshot |
+| Compile errors with line:column | `ALL_ERRORS` | `errors` |
+| Procedure/function signatures | `ALL_ARGUMENTS` | `args` |
+| Columns, types, nullability, defaults | `ALL_TAB_COLUMNS` | `cols` |
+| Object-level dependency graph | `ALL_DEPENDENCIES` | `deps`, `impact` |
+| Identifier declarations and usages | `ALL_IDENTIFIERS` (PL/Scope) | `plscope` |
+| SQL statements inside PL/SQL, per table | `ALL_STATEMENTS` (PL/Scope) | `plscope` on a table |
+| DDL reconstruction | `DBMS_METADATA.GET_DDL` | `ddl` |
+| Session's dangerous privileges | `SESSION_PRIVS` | `check` warning |
+
+`ALL_*` views show what the connected user has rights on. Empty results can
+mean "does not exist" or "not visible to this user" — with a least-privilege
+setup, prefer the proxy connection so visibility matches the schema owner's.
+
+## PL/Scope
+
+PL/Scope data exists only for objects compiled while it was enabled:
+
+```sql
+ALTER SESSION SET plscope_settings = 'IDENTIFIERS:ALL, STATEMENTS:ALL';
+ALTER PROCEDURE <name> COMPILE;
+```
+
+- Statement capture (`ALL_STATEMENTS`) needs Oracle 12.2+.
+- Recompiling objects on a **shared** schema affects everyone using it —
+  agree it with the team first. pythia never runs these for you.
+- Check what an object was compiled with: `ALL_PLSQL_OBJECT_SETTINGS`
+  (`PLSCOPE_SETTINGS` column).
+
+## DBMS_METADATA notes
+
+`ddl` disables `STORAGE` and `SEGMENT_ATTRIBUTES` transforms deliberately:
+segment clauses are noise for code review and burn context. If you need
+tablespace/storage detail, ask with `pythia sql` against `DBA_/ALL_SEGMENTS`
+(subject to privileges).
+
+## Licensing boundary — stay on the free side by default
+
+Safe on every edition, no extra license:
+
+- All `ALL_*` / `USER_*` dictionary views used above
+- `V$SESSION`, `EXPLAIN PLAN`, Statspack
+
+**Extra-cost** — do not query these unless the site confirms the license:
+
+- `DBA_HIST_*` (AWR) — requires Diagnostics Pack
+- SQL Performance Analyzer / SQL Tuning Advisor — Tuning/RAT packs
+
+pythia's built-in queries are license-safe. When writing free-form `sql`,
+keep to the free list unless told otherwise — a senior DBA reads restraint
+here as a sign the tooling understands Oracle.

pythia_skills/plsql-impact/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: plsql-impact
+description: Use before proposing or writing any change to an Oracle object - a procedure, package, function, trigger, view, or table. Impact analysis comes first, because what depends on an object decides how careful the change must be, and Oracle invalidates dependents in cascade.
+---
+
+# Impact Before Change
+
+**Announce at start:** "Using plsql-impact to measure the blast radius first."
+
+Changing an Oracle object recompiles or invalidates everything that depends
+on it — immediately, schema-wide, for every user of a shared database. The
+cost of knowing first is one command.
+
+## The Iron Law
+
+```
+NO CHANGE PROPOSED WITHOUT ITS IMPACT MEASURED FIRST
+```
+
+## The Workflow
+
+1. `pythia impact <OBJECT> --depth 2` — everything that depends on it,
+   as a tree, ending with the line that matters:
+   `-- impact: N dependent objects, M currently VALID`.
+2. `pythia deps <OBJECT> --depth 2` — the other direction, what it uses;
+   read it when the change touches calls or table access.
+3. `pythia invalid` — the baseline. Anything already INVALID before the
+   change must not be blamed on the change later; apply compares against
+   this automatically, but you should know the starting state too.
+
+## Reading the numbers
+
+| Result | What to do |
+|---|---|
+| 0 dependents | Say so and proceed; verify after apply anyway. |
+| 1–9 dependents | List them to the developer alongside the proposal. |
+| 10+ dependents, or any cross-schema dependent | Show the tree and get an explicit go-ahead **before writing any code**. |
+| Dependents already INVALID | Point them out — the area is already unstable. |
+
+Tables deserve the same treatment as code: `impact` on a table shows every
+program that would be invalidated by an `ALTER`.
+
+## Red Flags — STOP if you catch yourself thinking
+
+| Thought | Reality |
+|---------|---------|
+| "It's just a small helper" | Helpers are the most-depended-on objects there are. |
+| "I'll check impact after writing the code" | Then the number cannot change the design. Too late. |
+| "The preview in apply shows impact anyway" | That line is confirmation of a number you already knew — not discovery. |
+| "It's a new object, nothing depends on it" | True — say that, with `impact` output as evidence, not as an assumption. |
+
+## Hand-off
+
+Impact known and acceptable → `plsql-write` to write the change following
+the codebase's conventions → `plsql-apply` to land it with preview and
+verification.

pythia_skills/plsql-review/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: plsql-review
+description: Use when reviewing PL/SQL - a changed procedure or package, a proposed file, or an object suspected of causing trouble. Combines the database's own correctness signals with the antipattern checklist, and reports findings anchored to line numbers.
+---
+
+# Reviewing PL/SQL
+
+**Announce at start:** "Using plsql-review — checking the database's signals first."
+
+Review in two passes: what the database *knows* is wrong, then what the
+checklist says is *likely* wrong. Machine signals first — they are free and
+exact.
+
+## Pass 1 — the database's own verdict
+
+1. `pythia errors NAME` — compile errors and warnings with line:column.
+   An object that does not compile needs no style review yet.
+2. `pythia src NAME` — read the source with the compiler's line numbers, so
+   findings can be anchored (`line 47: ...`).
+3. `pythia impact NAME --depth 2` — how exposed is this object; a finding in
+   something with 40 dependents outranks the same finding in a leaf.
+4. For a proposed file (not yet applied): the compile verdict arrives at
+   apply time — say explicitly that compilation is still unverified.
+
+## Pass 2 — the antipattern checklist
+
+Work through `reference/antipatterns.md` — and the project's own
+`.pythia/conventions.md` when it exists, which outranks the generic list.
+The seven entries, each with
+wrong → right → why: row-by-row cursor loops, string-concatenated dynamic
+SQL, `WHEN OTHERS THEN NULL`, `COMMIT` inside loops, hand-copied types
+instead of `%TYPE`/`%ROWTYPE`, large OUT parameters without `NOCOPY`, and
+convention drift against the codebase (`pythia similar` shows the house
+style).
+
+## Reporting findings
+
+- Anchor every finding: `line N: <what> — <why it bites> — <the fix>`.
+- Severity order: breaks correctness → silently loses data or errors →
+  performance at scale → style drift.
+- Verify the claim before writing it: read the actual lines with `src`;
+  never report from memory of the diff alone.
+- A clean review says what was checked, not just "looks good": compiles
+  clean, no new INVALID, checklist passed.
+
+## When NOT to use this skill
+
+- Reviewing whether a change is *safe to apply* — that is `plsql-impact`
+  plus `plsql-apply`'s preview; this skill judges the code itself.
+- Reviewing non-PL/SQL application code — outside this skill's scope.

pythia_skills/plsql-review/reference/antipatterns.md

@@ -0,0 +1,106 @@
+# PL/SQL antipatterns
+
+Seven findings that recur in real codebases. Each: how it looks, what to
+write instead, and why it bites. Anchor findings to line numbers from
+`pythia src`.
+
+## 1. Row-by-row cursor loop doing DML
+
+**Wrong**
+```sql
+FOR r IN (SELECT id FROM t_order WHERE status = 'NEW') LOOP
+  UPDATE t_order SET status = 'DONE' WHERE id = r.id;
+END LOOP;
+```
+**Right** — `BULK COLLECT ... LIMIT` + `FORALL` (see patterns.md for the
+full template), or better: one set-based `UPDATE` when no per-row logic
+exists.
+**Why** — a context switch per row; thousands of rows means thousands of
+switches. The set-based form is also atomic.
+
+## 2. Dynamic SQL built by concatenation
+
+**Wrong**
+```sql
+EXECUTE IMMEDIATE 'DELETE FROM t_log WHERE id = ' || p_id;
+```
+**Right**
+```sql
+EXECUTE IMMEDIATE 'DELETE FROM t_log WHERE id = :1' USING p_id;
+```
+**Why** — SQL injection when the value is user-reachable, and a hard parse
+per distinct value even when it is not: shared-pool churn that hits the
+whole instance, not just this session.
+
+## 3. `WHEN OTHERS THEN NULL`
+
+**Wrong**
+```sql
+EXCEPTION WHEN OTHERS THEN NULL;
+```
+**Right** — handle the exceptions you can name; for the rest, log and
+`RAISE`.
+**Why** — every future bug in the block becomes silent wrong data. The
+worst version is around a `SELECT INTO`, where it also hides
+`TOO_MANY_ROWS` — a data-quality alarm.
+
+## 4. `COMMIT` inside a loop
+
+**Wrong**
+```sql
+FOR r IN c LOOP
+  process(r);
+  COMMIT;                -- "to be safe"
+END LOOP;
+```
+**Right** — commit once, at the transaction's owner (usually the outermost
+caller). For huge volumes, batch commits at a documented interval are a
+deliberate, named decision — not a reflex.
+**Why** — a failure mid-loop leaves a half-applied state that can be
+neither completed nor rolled back; it also breaks any caller that thought
+it owned the transaction, and `ORA-01555` risk goes up, not down.
+
+## 5. Hand-copied types instead of `%TYPE` / `%ROWTYPE`
+
+**Wrong**
+```sql
+v_name VARCHAR2(50);     -- the column is VARCHAR2(100) since 2024
+```
+**Right**
+```sql
+v_name customers.name%TYPE;
+```
+**Why** — the declaration is a snapshot that silently drifts from the
+schema; the failure arrives later as `VALUE_ERROR` on production data.
+
+## 6. Large OUT parameters without `NOCOPY`
+
+**Wrong**
+```sql
+PROCEDURE render(p_out IN OUT CLOB);
+```
+**Right**
+```sql
+PROCEDURE render(p_out IN OUT NOCOPY CLOB);
+```
+**Why** — IN OUT copies on entry and exit; for CLOBs and big collections
+that is real memory and time per call.
+
+## 7. Style drift from the codebase
+
+**Wrong** — new naming scheme, new cursor style, new comment format,
+introduced silently in one procedure.
+**Right** — `pythia similar` + `pythia src` on the top hits; match them.
+Propose style improvements to the developer as a separate conversation.
+**Why** — a mixed-style codebase costs every future reader; consistency is
+a feature maintainers can feel.
+
+## Reporting format
+
+```
+line 47: WHEN OTHERS THEN NULL — swallows every error including
+         TOO_MANY_ROWS — handle NO_DATA_FOUND explicitly, log and RAISE the rest
+```
+
+Severity order: correctness → silent data/error loss → performance at
+scale → style.

pythia_skills/plsql-setup/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: plsql-setup
+description: Use when setting pythia up for a project or a machine - writing connections.json, creating a least-privilege agent user, wiring the SQLcl MCP server, or diagnosing a connection that will not open. Also the place to start when check prints a privilege warning.
+---
+
+# Setting Up
+
+**Announce at start:** "Using plsql-setup to configure the database access."
+
+Set up in this order: connection first (everything else needs it), the
+least-privilege user second (the only protection that cannot be bypassed),
+SQLcl MCP last (optional, reads only).
+
+## 1. Connection
+
+Create `.pythia/connections.json` at the project root — `pythia install`
+scaffolds it (pip installs: `pip install pythia-plsql`), or copy
+`examples/connections.example.json` from a clone. Fill it in. Rules pythia
+applies:
+
+- One entry: used as-is. Several entries: the path segment directly under the
+  project root picks one (`root/DEV/...` → `DEV`), else the entry named by a
+  top-level `"default": "<name>"`. Ambiguity is an error, never a guess.
+- `--conn NAME` and `PYTHIA_CONNECTION` override everything; the
+  `PYTHIA_USER/PYTHIA_PASSWORD/PYTHIA_DSN` variables bypass the file.
+- The file holds credentials: it is gitignored — keep it that way, and keep
+  it out of chat and screenshots.
+
+Verify with `pythia check`: it prints who you are connected as and object
+counts. A failure names the connection and what to check.
+
+## 2. The agent's database user — the real protection
+
+The policy file is an application-side fence; **Oracle grants are the only
+layer an agent cannot walk around.** Oracle has no clean per-object form of
+"may edit PL/SQL in that schema" — compiling into another schema needs
+`CREATE ANY PROCEDURE`, which spans every schema on the instance.
+
+The workable pattern is **proxy authentication**: a logon-only user that
+connects *through* the schema owner. The agent never learns the owner's
+password, revocation is one statement, the audit trail shows who really
+connected, and the blast radius is the one development schema.
+
+Run `examples/agent-user-setup.example.sql` (as a DBA, names adapted), then
+set the connection's user to `"agent_user[schema_owner]"`.
+
+Oracle's own guidance for LLM access, follow it: grant minimum privileges,
+never point an LLM at a production database, audit its activity regularly.
+
+`pythia check` warns on one line when the session holds `%ANY%` privileges or
+runs as the schema owner directly. The goal state is: no warning.
+
+## 3. SQLcl MCP server (optional, reads only)
+
+If SQLcl 25.2+ is installed, agents can read through Oracle's official MCP
+server: command `sql -mcp`. Example client config:
+
+```json
+{"mcpServers": {"sqlcl": {"command": "sql", "args": ["-mcp"]}}}
+```
+
+- Keep the default restrict level (`-R 4`, most restrictive): it blocks host
+  commands and `@` scripts. Note it does NOT block DML/DDL inside `run-sql` —
+  which is why **writes never go through MCP**: only `pythia apply` has the
+  snapshot, preview, verify and journal.
+- Built-in audit, worth telling the DBA about: every interaction lands in
+  `DBTOOLS$MCP_LOG`; `V$SESSION.MODULE` shows the MCP client and
+  `V$SESSION.ACTION` the LLM's name; generated SQL carries an
+  `/* LLM in use */` comment.
+
+## Done when
+
+- `pythia check` connects, shows the right schema, and prints **no**
+  privilege warning.
+- `pythia policy` prints the write policy and the rollback table.
+- The credentials file is untracked (`git status` does not show it).

pythia_skills/plsql-skill-author/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: plsql-skill-author
+description: Use when the developer wants their own way of working captured as a new skill - "make a skill for how we do X", a house convention or preference worth teaching every future session, a team ritual, or the same correction arriving for the second time. Interviews the developer, mines the real conventions from the database, and writes a skill in this pack's format.
+---
+
+# Authoring a New Skill
+
+**Announce at start:** "Using plsql-skill-author — let's capture how you actually work."
+
+A skill is a decision captured so it never has to be re-argued. Capture what
+the team *actually does* — with evidence from the database — not what anyone
+remembers about it.
+
+## Step 1 — Interview, one question at a time
+
+Ask, in order, waiting for each answer:
+
+1. **What task is this for?» One skill per concern — "our report procedure
+   ritual" is one skill; "everything about our team" is not.
+2. **When should it trigger?** Collect the developer's *own words* — the
+   phrases they would type ("làm báo cáo", "clone the export proc", an error
+   code, a file pattern). These go into the description verbatim; triggering
+   lives or dies on them.
+3. **Which parts are law, which are taste?** Hard rules get an Iron Law and
+   a red-flags table; preferences get a "default unless told otherwise".
+4. **What does *wrong* look like?** Past incidents make the best red-flag
+   rows.
+
+## Step 2 — Mine the evidence
+
+Memory lies; the schema does not. Before writing a line:
+
+- `pythia similar <TYPICAL_NAME>` → which family of programs embodies this
+  workflow; open the top hits with `pythia src` and extract the *actual*
+  naming, parameter and structure conventions.
+- `pythia args` / `pythia cols` for the signatures and types the skill will
+  tell people to use.
+- Save two or three short **verbatim** snippets as examples — real code
+  outranks invented code.
+
+## Step 3 — Draft in the house format
+
+- Frontmatter: kebab-case `name` matching the folder; `description` that
+  opens with the trigger condition (`Use when ...`) and contains the
+  developer's phrases from step 1.
+- Body budget ~150 lines. Long material (templates, checklists, snippet
+  libraries) goes to `reference/` and is linked, not pasted.
+- Structure menu — use what the answers call for, skip the rest:
+  Iron Law (one line, caps) · numbered workflow · red-flags table
+  ("thought → reality") · "When NOT to use" · an **Announce at start** line.
+- Write in the language the team works in; this pack is English, a private
+  team skill may be Vietnamese — the developer decides.
+
+**Not everything needs a skill.** Pure naming and style rules travel better
+as `.pythia/conventions.json` (machine-checked at every apply preview) plus
+`.pythia/conventions.md` (prose the agent reads). Reserve skills for
+workflows — things with steps, gates and judgment.
+
+## Step 4 — Place it
+
+User skills live in the **developer's project**, e.g.
+`.claude/skills/<name>/SKILL.md` for Claude Code (other agents: the layout
+`skills/<name>/SKILL.md` works with `npx skills add`). Never write into the
+installed pythia pack — updates would overwrite it, and the pack's lint
+enforces its own fixed skill list.
+
+## Step 5 — Verify it triggers
+
+In a **fresh session**, give a task phrased the way the developer would
+really ask (step 2's phrases). The skill must activate unprompted. If it
+does not, the description is the bug: sharpen it with the exact phrases that
+failed, and test again.
+
+## Keep it alive
+
+When the developer corrects the agent for the same thing twice, propose
+folding that correction into the skill — that is the skill earning its keep.
+Retire rules that stopped being true; a stale skill is worse than none.
+
+## Before sharing outside the team
+
+Run the hygiene check this pack applies to itself: no hosts, schema names,
+credentials, or internal identifiers in the skill or its references. What is
+fine in a private repo is a leak in a public one.
+
+## Red Flags — STOP if you catch yourself thinking
+
+| Thought | Reality |
+|---------|---------|
+| "I'll write it from memory of this chat" | Mine `similar`/`src` first — the codebase is the authority. |
+| "One big skill covering everything" | One concern per skill, or nothing triggers cleanly. |
+| "Paste the whole style guide in" | Budget is ~150 lines; long material goes to reference/. |
+| "The description can be generic" | Generic descriptions never trigger. Use the developer's own phrases. |
+| "It works, no need to test triggering" | Untested triggering = a skill nobody ever sees again. |

pythia_skills/plsql-write/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: plsql-write
+description: Use when writing or modifying PL/SQL source - a procedure, function, package, trigger, or view - after impact is known. The codebase's conventions already exist; copy them instead of inventing style, and anchor every type to the database's reality.
+---
+
+# Writing PL/SQL
+
+**Announce at start:** "Using plsql-write — mining the codebase's conventions first."
+
+**Before anything:** if the project has `.pythia/conventions.md`, read it —
+house rules there outrank every generic pattern below, and
+`pythia conventions` shows the naming patterns the apply preview will check.
+
+A codebase with thousands of procedures has already decided how procedures
+look. Your job is to write one that a maintainer cannot tell from the
+existing ones — not to introduce a better style.
+
+## The Workflow
+
+1. **Find the models.** `pythia similar <NEW_NAME>` ranks existing programs
+   sharing name tokens; the `MATCHED_TOKENS` column says why. Open the top
+   two or three with `pythia src` and imitate: naming, parameter prefixes,
+   cursor style, error handling, comment style.
+2. **Anchor the signatures.** For every program you call:
+   `pythia args NAME` — real parameter names, order, types, defaults. Never
+   guess a signature from memory of similar code.
+3. **Anchor the types.** For every table you touch: `pythia cols TABLE` —
+   then declare variables with `%TYPE` / `%ROWTYPE` against those columns
+   instead of copying the current type by hand. The declaration then
+   survives column changes.
+4. **Write the file.** Rules the write path enforces — follow them here:
+   - **One object per file.** Package spec and body are two files.
+   - End the file with the PL/SQL block's `;` and a final line holding `/`.
+   - Name the object unqualified, or qualified with the exact schema the
+     connection targets — a mismatch is refused at apply time.
+5. **Check yourself before handing off.** Reread against
+   `reference/patterns.md` — cursor and bulk patterns, exception discipline,
+   bind variables, commit ownership.
+
+## Conventions outrank preferences
+
+If the codebase writes explicit cursors where you would write `FOR r IN`,
+write explicit cursors. If its parameter prefixes look dated, use them
+anyway. A mixed-style codebase is worse than a consistently dated one —
+propose style changes to the developer separately, never silently.
+
+## When NOT to use this skill
+
+- Understanding existing code → `plsql-explore`.
+- Measuring what a change breaks → `plsql-impact` (must already be done).
+- Landing the file on the database → `plsql-apply`, always — never
+  `run-sql`, never `sqlplus`.

pythia_skills/plsql-write/reference/patterns.md

@@ -0,0 +1,99 @@
+# PL/SQL patterns worth copying
+
+Generic patterns for when the codebase gives no model to imitate. When the
+codebase disagrees with this file, **the codebase wins** — consistency beats
+preference.
+
+## Anchor declarations to the dictionary
+
+```sql
+-- fragile: copies today's type by hand
+v_customer_name VARCHAR2(100);
+
+-- survives column changes
+v_customer_name customers.name%TYPE;
+r_order         orders%ROWTYPE;
+```
+
+## Bulk over row-by-row
+
+```sql
+-- slow at scale: one context switch per row
+FOR r IN (SELECT id FROM t_order WHERE status = 'NEW') LOOP
+  process_order(r.id);
+END LOOP;
+
+-- bulk: fetch in batches, write with FORALL
+DECLARE
+  TYPE t_ids IS TABLE OF t_order.id%TYPE;
+  v_ids t_ids;
+  CURSOR c IS SELECT id FROM t_order WHERE status = 'NEW';
+BEGIN
+  OPEN c;
+  LOOP
+    FETCH c BULK COLLECT INTO v_ids LIMIT 500;
+    EXIT WHEN v_ids.COUNT = 0;
+    FORALL i IN 1 .. v_ids.COUNT
+      UPDATE t_order SET status = 'DONE' WHERE id = v_ids(i);
+  END LOOP;
+  CLOSE c;
+END;
+```
+
+The `LIMIT` matters: unbounded `BULK COLLECT` trades the row-switch problem
+for a memory problem.
+
+## Exceptions: handle what you can name, re-raise the rest
+
+```sql
+BEGIN
+  ...
+EXCEPTION
+  WHEN NO_DATA_FOUND THEN
+    RETURN NULL;                       -- a decision, made on purpose
+  WHEN OTHERS THEN
+    log_error(sqlcode, sqlerrm, 'PKG_ORDER.calc_total');
+    RAISE;                             -- never swallow; the caller must know
+END;
+```
+
+`WHEN OTHERS` without `RAISE` (or `RAISE_APPLICATION_ERROR`) converts every
+future bug into silent wrong data.
+
+## Dynamic SQL: binds, never concatenation
+
+```sql
+-- injection + hard parse per call
+EXECUTE IMMEDIATE 'SELECT total FROM t_order WHERE id = ' || p_id INTO v_t;
+
+-- shared cursor, safe
+EXECUTE IMMEDIATE 'SELECT total FROM t_order WHERE id = :1'
+  INTO v_t USING p_id;
+```
+
+Identifiers (table names) cannot be bound — validate them against
+`ALL_TABLES`/`ALL_OBJECTS` before splicing, and say so in a comment.
+
+## Commit ownership
+
+Utility and business procedures do not `COMMIT`; the outermost caller — the
+one that knows the transaction's boundaries — does. A procedure that commits
+mid-loop turns a failed run into a half-applied state nobody can reason
+about, and breaks the caller's ability to roll back.
+
+## Large OUT parameters
+
+```sql
+PROCEDURE render_report(p_clob IN OUT NOCOPY CLOB);
+```
+
+Without `NOCOPY`, IN OUT copies the value both ways; for big CLOBs and
+collections that is real memory and time. (It is a hint, not a guarantee —
+still worth writing.)
+
+## Naming: mine, don't invent
+
+Before naming anything: `pythia similar <intended_name>` and copy the
+dominant token order, prefixes and casing of the top hits. Parameter
+prefixes, cursor names, and constant style come from `pythia src` of a
+neighboring program — not from this file.