pythia-plsql 0.2.0__tar.gz → 0.3.0__tar.gz

{pythia_plsql-0.2.0/scripts/pythia_plsql.egg-info → pythia_plsql-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythia-plsql
-Version: 0.2.0
+Version: 0.3.0
 Summary: PL/SQL development for AI agents on Oracle Database - expert data-dictionary queries, impact analysis, and a snapshot-verified write path with honest rollback.
 License: MIT
 Project-URL: Homepage, https://github.com/thaildhe172591/pythia
@@ -20,7 +20,7 @@ Dynamic: license-file
 
 > Oracle's MCP gives your agent a connection. **pythia gives it the judgment to use it.**
 
-**English** · [Tiếng Việt](README.vi.md)
+**English** · [Tiếng Việt](README.vi.md) · **[The Complete Guide →](GUIDE.md)**
 
 [![ci](https://github.com/thaildhe172591/pythia/actions/workflows/ci.yml/badge.svg)](https://github.com/thaildhe172591/pythia/actions/workflows/ci.yml)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
@@ -81,9 +81,10 @@ pythia check               # fill in connections.json first, then verify
 
 The pip package is the whole kit: with Node.js present, `pythia install`
 runs `npx skills add` (77 agents, symlinked updates; `--source <git-url>`
-for internal mirrors) — without Node it copies the bundled skill pack into
-`.agents/skills/`, the universal layout Claude Code, Codex and Cursor all
-read (one copy, so no skill shows up twice). Skills alone: `npx skills add
+for internal mirrors) — without Node it copies the bundled pack itself.
+Prefer **global skills**: `pythia install -g` once per machine serves every
+project, and per-project installs then skip the skills step automatically —
+one copy anywhere means no skill ever shows up twice in the agent's menu. Skills alone: `npx skills add
 thaildhe172591/pythia`, or `/plugin marketplace add thaildhe172591/pythia`.
 
 `pip install` is **once per machine**; `pythia install` is **once per
@@ -92,6 +93,15 @@ project** — run it in each repo's root to drop the skills and a fresh
 project you are standing in (searched upward from the current directory,
 no global fallback), so one global CLI never mixes up databases.
 
+**Updating** follows the same split:
+
+```bash
+pip install --upgrade pythia-plsql   # new CLI version (once per machine)
+pythia install                       # refresh a project's skills; config never touched
+```
+
+(`npx skills update` also works for skills installed via npx.)
+
 Running from a clone works too — `python scripts/pythia.py <command>`; every
 printed follow-up command matches how you invoked it. Windows, macOS, Linux
 and WSL are all CI-tested.
@@ -121,12 +131,18 @@ every agent read them first (`pythia conventions` shows both).
 
 **The account is the real security layer** — the policy file is an application-side
 fence. Give the agent its own revocable credential with proxy authentication
-(`agent_user[schema_owner]`, no `ANY` privileges, no owner password shared).
-`pythia agent-user` generates that SQL for your current connection — password
-included, `--save` drops the credential into `connections.json` — but it is
-optional convenience: running
+(`agent_user[schema_owner]`, no `ANY` privileges, no owner password shared):
+
+```bash
+pythia agent-user --save   # SQL for the DBA + matching credential saved as <conn>_agent
+pythia check               # after the DBA ran it: proxy session, warning gone
+```
+
+One run does both — the password is regenerated each run, so the SQL and the
+saved config must come from the same run. Optional convenience: doing it by
+hand with
 [`examples/agent-user-setup.example.sql`](examples/agent-user-setup.example.sql)
-by hand works just as well.
+works just as well.
 `pythia check` warns when the session runs with more power than the task needs.
 
 Per-group write policy, `.pythia/policy.json` (defaults shown):

{pythia_plsql-0.2.0 → pythia_plsql-0.3.0}/README.md

@@ -6,7 +6,7 @@
 
 > Oracle's MCP gives your agent a connection. **pythia gives it the judgment to use it.**
 
-**English** · [Tiếng Việt](README.vi.md)
+**English** · [Tiếng Việt](README.vi.md) · **[The Complete Guide →](GUIDE.md)**
 
 [![ci](https://github.com/thaildhe172591/pythia/actions/workflows/ci.yml/badge.svg)](https://github.com/thaildhe172591/pythia/actions/workflows/ci.yml)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
@@ -67,9 +67,10 @@ pythia check               # fill in connections.json first, then verify
 
 The pip package is the whole kit: with Node.js present, `pythia install`
 runs `npx skills add` (77 agents, symlinked updates; `--source <git-url>`
-for internal mirrors) — without Node it copies the bundled skill pack into
-`.agents/skills/`, the universal layout Claude Code, Codex and Cursor all
-read (one copy, so no skill shows up twice). Skills alone: `npx skills add
+for internal mirrors) — without Node it copies the bundled pack itself.
+Prefer **global skills**: `pythia install -g` once per machine serves every
+project, and per-project installs then skip the skills step automatically —
+one copy anywhere means no skill ever shows up twice in the agent's menu. Skills alone: `npx skills add
 thaildhe172591/pythia`, or `/plugin marketplace add thaildhe172591/pythia`.
 
 `pip install` is **once per machine**; `pythia install` is **once per
@@ -78,6 +79,15 @@ project** — run it in each repo's root to drop the skills and a fresh
 project you are standing in (searched upward from the current directory,
 no global fallback), so one global CLI never mixes up databases.
 
+**Updating** follows the same split:
+
+```bash
+pip install --upgrade pythia-plsql   # new CLI version (once per machine)
+pythia install                       # refresh a project's skills; config never touched
+```
+
+(`npx skills update` also works for skills installed via npx.)
+
 Running from a clone works too — `python scripts/pythia.py <command>`; every
 printed follow-up command matches how you invoked it. Windows, macOS, Linux
 and WSL are all CI-tested.
@@ -107,12 +117,18 @@ every agent read them first (`pythia conventions` shows both).
 
 **The account is the real security layer** — the policy file is an application-side
 fence. Give the agent its own revocable credential with proxy authentication
-(`agent_user[schema_owner]`, no `ANY` privileges, no owner password shared).
-`pythia agent-user` generates that SQL for your current connection — password
-included, `--save` drops the credential into `connections.json` — but it is
-optional convenience: running
+(`agent_user[schema_owner]`, no `ANY` privileges, no owner password shared):
+
+```bash
+pythia agent-user --save   # SQL for the DBA + matching credential saved as <conn>_agent
+pythia check               # after the DBA ran it: proxy session, warning gone
+```
+
+One run does both — the password is regenerated each run, so the SQL and the
+saved config must come from the same run. Optional convenience: doing it by
+hand with
 [`examples/agent-user-setup.example.sql`](examples/agent-user-setup.example.sql)
-by hand works just as well.
+works just as well.
 `pythia check` warns when the session runs with more power than the task needs.
 
 Per-group write policy, `.pythia/policy.json` (defaults shown):

{pythia_plsql-0.2.0 → pythia_plsql-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pythia-plsql"
-version = "0.2.0"
+version = "0.3.0"
 description = "PL/SQL development for AI agents on Oracle Database - expert data-dictionary queries, impact analysis, and a snapshot-verified write path with honest rollback."
 readme = "README.md"
 license = { text = "MIT" }

{pythia_plsql-0.2.0 → pythia_plsql-0.3.0}/scripts/pythia.py

@@ -201,6 +201,19 @@ def invocation():
     return pathlib.Path(prog).name
 
 
+def human_at_the_keyboard():
+    """True only when a person is typing: stdin is a TTY. An agent driving
+    the CLI through a subprocess has no TTY and cannot fake one — which is
+    exactly why the loosening actions below key on this. PYTHIA_CI=1 is the
+    documented escape for real pipelines."""
+    if os.environ.get("PYTHIA_CI"):
+        return True
+    try:
+        return sys.stdin.isatty()
+    except (AttributeError, ValueError):
+        return False
+
+
 def forbid_write_flag(argv):
     if "--write" in argv:
         sys.exit(f"There is no --write flag. The write path is `{invocation()} "
@@ -1110,6 +1123,12 @@ def run_apply(conn, schema, ns, file_text, origin=None):
                             {"s": schema, "n": name, "t": otype})
         db_source = "".join(cell(r[0]) for r in rows)
     token = apply_token(otype, name, file_text, db_source)
+    if ns.yes and not human_at_the_keyboard():
+        sys.exit("--yes is the developer's flag, and no terminal is attached "
+                 "to this session.\nAgents preview, relay the diff and the "
+                 "impact verbatim, STOP, and pass --confirm <token> only "
+                 "after the developer's explicit approval in chat.\n"
+                 "(Real pipelines set PYTHIA_CI=1.)")
     confirmed = bool(ns.yes) or ns.confirm == token
     if ns.confirm and ns.confirm != token:
         sys.exit("The confirmation token does not match: the file or the "
@@ -1120,6 +1139,9 @@ def run_apply(conn, schema, ns, file_text, origin=None):
     invalid_before = [(r[0], r[1]) for r in inv_rows]
     meta = {"schema": schema, "connection": ns.conn_name, "group": group,
             "token": token, "applied": False,
+            "confirmed_via": ("yes" if ns.yes else
+                              "token" if confirmed else "preview"),
+            "tty": human_at_the_keyboard(),
             "invalid_before": invalid_before, **(origin or {})}
     entry = write_journal_entry(ns.project_root, otype, name, db_source,
                                 file_text, meta)
@@ -1263,6 +1285,16 @@ def cmd_policy(conn, schema, ns):
                  "values: allow, confirm, deny.")
     if ns.action == "set":
         eff = load_policy(ns.project_root)
+        RANK = {"deny": 0, "confirm": 1, "allow": 2}
+        if (RANK[ns.value] > RANK[eff[ns.group][0]]
+                and not human_at_the_keyboard()):
+            sys.exit(f"Loosening the write policy ({ns.group}: "
+                     f"{eff[ns.group][0]} → {ns.value}) is the developer's "
+                     "decision, and no terminal is attached to this session."
+                     "\nAsk the developer to run this themselves:\n"
+                     f"  {invocation()} policy set {ns.group} {ns.value}\n"
+                     "(Tightening is always allowed; pipelines set "
+                     "PYTHIA_CI=1.)")
         eff[ns.group] = (ns.value, "policy.json")   # validated by argparse choices
         path = policy_path(ns.project_root)
         path.parent.mkdir(parents=True, exist_ok=True)
@@ -1355,7 +1387,7 @@ AGENT_USER_SQL = """\
 -- privileges, utility grants — the agent needs none of them to develop
 -- PL/SQL, and every extra grant widens the blast radius.
 
-CREATE USER {agent} IDENTIFIED BY "{password}";
+{create_line}
 GRANT CREATE SESSION TO {agent};
 ALTER USER {owner} GRANT CONNECT THROUGH {agent};
 
@@ -1365,6 +1397,23 @@ ALTER USER {owner} GRANT CONNECT THROUGH {agent};
 """
 
 
+def agent_user_sql(owner, agent, password, exists):
+    """exists True: the user is already there — CREATE would be ORA-01920,
+    so reset the password and unlock in one statement (harmless if it was
+    never locked). exists None: no database to ask — emit CREATE plus the
+    fallback as a comment so the DBA can pick."""
+    if exists:
+        line = (f'ALTER USER {agent} IDENTIFIED BY "{password}" ACCOUNT '
+                f"UNLOCK;  -- user already exists; CREATE would be ORA-01920")
+    else:
+        line = f'CREATE USER {agent} IDENTIFIED BY "{password}";'
+        if exists is None:
+            line += ("\n-- (if the user already exists — ORA-01920 — run "
+                     "instead:\n--  ALTER USER "
+                     f'{agent} IDENTIFIED BY "{password}" ACCOUNT UNLOCK;)')
+    return AGENT_USER_SQL.format(owner=owner, agent=agent, create_line=line)
+
+
 def agent_password():
     """Random password satisfying common Oracle verify functions: letter
     first, upper+lower+digit+special, 16+ chars. Always quoted in SQL."""
@@ -1403,18 +1452,51 @@ def cmd_agent_user(conn, schema, ns):
                  f"({base['user']}) — nothing to set up.")
     agent = (ns.name or f"{owner}_AGENT").upper()
     password = agent_password()
-    print(AGENT_USER_SQL.format(owner=owner, agent=agent, password=password))
+    exists, dangerous = None, None
+    if conn is not None:
+        _, rows = run_query(conn, "select username from all_users "
+                                  "where username = :n", {"n": agent})
+        exists = bool(rows)
+        _, prows = run_query(conn, load_query("session-privileges.sql"))
+        dangerous = [r[0] for r in prows]
+    sql = agent_user_sql(owner, agent, password, exists)
+    saved = None
     if ns.save:
-        name = save_agent_connection(root, base_name, base, agent, password)
-        print(f"Saved connection '{name}' (now the default) in "
-              f"{pathlib.Path(root) / CONFIG_DIR / CONFIG_NAME};\n"
+        saved = save_agent_connection(root, base_name, base, agent, password)
+    if ns.json:
+        print(json.dumps({
+            "owner": owner, "agent": agent, "password": password, "sql": sql,
+            "agent_user_exists": exists, "saved_connection": saved,
+            "owner_connection": base_name,
+            "check_will_warn": bool(dangerous) if dangerous is not None else None,
+            "owner_dangerous_privs": dangerous,
+            "next": ["have a DBA run the sql", f"{invocation()} check"]}))
+        return
+    print(sql)
+    print("-- The password is regenerated on EVERY run — only the SQL from")
+    print("-- this exact run matches what --save writes. One run, not two.")
+    if dangerous:
+        print(f"\n! Even after this, {invocation()} check will STILL warn: "
+              f"the owner {owner} holds\n  {', '.join(dangerous[:3])}"
+              + ("…" if len(dangerous) > 3 else "")
+              + " — every proxy session inherits it.\n"
+              "  Trim the owner's grants to reach the no-warning goal state "
+              "(see README, Security).")
+    elif dangerous is not None:
+        print(f"\nOwner grants look clean: after the DBA runs this, "
+              f"{invocation()} check should pass with no warning.")
+    if saved:
+        print(f"\nSaved connection '{saved}' (now the default) in "
+              f"{pathlib.Path(root) / CONFIG_DIR / CONFIG_NAME} — its "
+              f"password matches the SQL above;\n"
               f"the owner entry '{base_name}' is untouched — switch back "
               f"any time with --conn {base_name}.")
-        print(f"\nNext: run the SQL above as a DBA, then: {invocation()} check")
+        print(f"\nNext: relay the SQL above to the developer verbatim for a "
+              f"DBA to run, then: {invocation()} check")
     else:
-        print(f"-- Rerun with --save to add this credential to "
-              f"connections.json as '{base_name}_agent' and make it the "
-              f"default once the DBA has run it.")
+        print(f"-- Nothing was saved. Use --save to also write this "
+              f"credential to connections.json as '{base_name}_agent' in "
+              f"the same run.")
 
 
 # unistr escapes. Single quote doubles to '' per SQL (a \' is ORA-01756 for
@@ -1489,7 +1571,7 @@ def scaffold_config(root):
     return path, True
 
 
-def run_skills_add(source, interactive=False):
+def run_skills_add(source, interactive=False, glob=False):
     """Install the skill pack via the skills CLI. Returns its exit code, or
     None when npx is absent — the caller then copies the bundled pack, so a
     machine with only Python still gets the whole kit. At a TTY the CLI's own
@@ -1499,10 +1581,22 @@ def run_skills_add(source, interactive=False):
     npx = shutil.which("npx")
     if npx is None:
         return None
+    return subprocess.run(skills_add_cmd(npx, source, interactive,
+                                         glob=glob)).returncode
+
+
+def skills_add_cmd(npx, source, interactive, glob=False):
+    """Interactive: the CLI's own agent picker. Non-interactive project
+    installs pin one agent target so nothing is double-installed; global
+    installs let the CLI place per-agent copies under the home directory."""
     cmd = [npx, "skills", "add", source]
+    if glob:
+        cmd.append("-g")
     if not interactive:
         cmd.append("-y")
-    return subprocess.run(cmd).returncode
+        if not glob:
+            cmd += ["-a", "claude-code"]
+    return cmd
 
 
 LEGACY_SKILLS = ("plsql-setup", "plsql-explore", "plsql-impact",
@@ -1510,43 +1604,100 @@ LEGACY_SKILLS = ("plsql-setup", "plsql-explore", "plsql-impact",
                  "plsql-skill-author")
 
 
-def copy_bundled_skills(root):
-    """No-Node fallback: copy the wheel-bundled pack into .agents/skills/
-    ONLY — the universal layout that Claude Code, Codex, Cursor, Copilot and
-    friends all read. A second copy in .claude/skills/ would show every
-    skill twice in Claude Code's menu. The copy merges: only the pack's own
-    skills are refreshed, anything else in the directory is untouched.
-    Stale copies under the pack's old plsql-* names are removed from both
-    conventional roots (real directories only, never symlinks)."""
+def pack_names():
+    return [p.name for p in sorted(SKILLS_DIR.iterdir())
+            if (p / "SKILL.md").is_file()]
+
+
+def global_pack_present(home=None):
+    """Is the skill pack already installed machine-wide? Then a project copy
+    would only duplicate every entry in the agent's menu."""
+    home = pathlib.Path(home) if home else pathlib.Path.home()
+    return any((home / rel / "pythia-apply" / "SKILL.md").is_file()
+               for rel in (".claude/skills", ".agents/skills",
+                           ".config/agents/skills"))
+
+
+def copy_bundled_skills(base_dir):
+    """No-Node fallback: copy the wheel-bundled pack into
+    <base>/.claude/skills/ ONLY — the directory Claude Code reliably reads
+    in both scopes (field evidence: project .agents/skills is invisible to
+    some Claude Code versions, and a second copy doubles every menu entry).
+    base_dir is the project root, or the home directory for -g. The copy
+    merges: only the pack's own skills are refreshed; stale copies of the
+    pack under .agents/skills and old plsql-* names are cleaned."""
     import shutil
-    dest_root = pathlib.Path(root) / ".agents" / "skills"
+    dest_root = pathlib.Path(base_dir) / ".claude" / "skills"
     for pack in sorted(SKILLS_DIR.iterdir()):
         if not (pack / "SKILL.md").is_file():
             continue
         shutil.copytree(pack, dest_root / pack.name, dirs_exist_ok=True)
+    clean_legacy_skills(base_dir)
+    for name in pack_names():   # canonical copy lives in .claude now
+        _remove_link_first(pathlib.Path(base_dir) / ".agents" / "skills" / name)
+    return [dest_root]
+
+
+def _remove_link_first(path):
+    """Windows junctions defeat is_symlink(); unlink/rmdir take out a file,
+    symlink, junction or empty dir without touching any target — only a
+    real populated directory needs rmtree."""
+    import shutil
+    if not os.path.lexists(path):
+        return
+    try:
+        path.unlink()
+    except OSError:
+        try:
+            os.rmdir(path)
+        except OSError:
+            shutil.rmtree(path)
+
+
+def clean_legacy_skills(base_dir):
+    """Remove stale copies under the pack's old plsql-* names from both
+    conventional roots below base_dir (project root or home)."""
     for rel in (".agents/skills", ".claude/skills"):
         for old_name in LEGACY_SKILLS:
-            legacy = pathlib.Path(root) / rel / old_name
-            if legacy.is_dir() and not legacy.is_symlink():
-                shutil.rmtree(legacy)
-    return [dest_root]
+            _remove_link_first(pathlib.Path(base_dir) / rel / old_name)
 
 
 def cmd_install(conn, schema, ns):
     en = getattr(ns, "color", False)
     if en:
         sys.stdout.write(banner(en))
+    interactive = sys.stdin.isatty() and sys.stdout.isatty()
+    if ns.glob:
+        code = run_skills_add(ns.source, interactive, glob=True)
+        if code is None:
+            for tgt in copy_bundled_skills(pathlib.Path.home()):
+                print(f"Copied the bundled skill pack into {tgt}")
+        elif code:
+            sys.exit(code)
+        else:
+            clean_legacy_skills(pathlib.Path.home())
+        print("\nGlobal skills serve every project — per-project installs "
+              "will now skip the skills step automatically.")
+        return
     path, created = scaffold_config(ns.project_root)
     print(f"{'Created' if created else 'Kept existing'} {path}")
-    interactive = sys.stdin.isatty() and sys.stdout.isatty()
-    code = run_skills_add(ns.source, interactive)
-    if code is None:
-        for t in copy_bundled_skills(ns.project_root):
-            print(f"Copied the bundled skill pack into {t}")
-        print("(npx not found — with Node.js, `npx skills add` reaches 77 "
-              "agents with symlinked updates.)")
-    elif code:
-        sys.exit(code)
+    if global_pack_present():
+        print("Skill pack found in the global install — it already serves "
+              "this project,\nso no project copy is made (a second copy "
+              f"doubles every menu entry).\nRefresh it with: {invocation()} "
+              "install -g")
+        clean_legacy_skills(ns.project_root)
+    else:
+        code = run_skills_add(ns.source, interactive)
+        if code is None:
+            for tgt in copy_bundled_skills(ns.project_root):
+                print(f"Copied the bundled skill pack into {tgt}")
+            print("(npx not found — with Node.js, `npx skills add` reaches "
+                  "77 agents with symlinked updates.)")
+        elif code:
+            sys.exit(code)
+        else:
+            clean_legacy_skills(ns.project_root)
     print(f"\nNext: fill in {path}")
     print(f"Then: {invocation()} check")
 
@@ -1559,8 +1710,7 @@ COMMANDS = {"check": cmd_check, "ls": cmd_ls, "src": cmd_src, "args": cmd_args,
             "conventions": cmd_conventions, "install": cmd_install,
             "unistr": cmd_unistr, "agent-user": cmd_agent_user}
 
-NO_DB_COMMANDS = {"policy", "journal", "conventions", "install", "unistr",
-                  "agent-user"}
+NO_DB_COMMANDS = {"policy", "journal", "conventions", "install", "unistr"}
 
 
 # --- CLI ---------------------------------------------------------------------
@@ -1674,6 +1824,9 @@ def build_parser():
                    help="wrap as 'loi:'||unistr(...)||':loi'")
     s = sub.add_parser("install", parents=[common()],
                        help="install the skill pack and scaffold .pythia/ config")
+    s.add_argument("-g", "--global", dest="glob", action="store_true",
+                   help="install the skill pack machine-wide (serves every "
+                        "project; per-project installs then skip skills)")
     s.add_argument("--source", default=DEFAULT_SKILLS_SOURCE,
                    help="skills repo for `npx skills add` "
                         f"(default {DEFAULT_SKILLS_SOURCE})")

{pythia_plsql-0.2.0 → pythia_plsql-0.3.0/scripts/pythia_plsql.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythia-plsql
-Version: 0.2.0
+Version: 0.3.0
 Summary: PL/SQL development for AI agents on Oracle Database - expert data-dictionary queries, impact analysis, and a snapshot-verified write path with honest rollback.
 License: MIT
 Project-URL: Homepage, https://github.com/thaildhe172591/pythia
@@ -20,7 +20,7 @@ Dynamic: license-file
 
 > Oracle's MCP gives your agent a connection. **pythia gives it the judgment to use it.**
 
-**English** · [Tiếng Việt](README.vi.md)
+**English** · [Tiếng Việt](README.vi.md) · **[The Complete Guide →](GUIDE.md)**
 
 [![ci](https://github.com/thaildhe172591/pythia/actions/workflows/ci.yml/badge.svg)](https://github.com/thaildhe172591/pythia/actions/workflows/ci.yml)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
@@ -81,9 +81,10 @@ pythia check               # fill in connections.json first, then verify
 
 The pip package is the whole kit: with Node.js present, `pythia install`
 runs `npx skills add` (77 agents, symlinked updates; `--source <git-url>`
-for internal mirrors) — without Node it copies the bundled skill pack into
-`.agents/skills/`, the universal layout Claude Code, Codex and Cursor all
-read (one copy, so no skill shows up twice). Skills alone: `npx skills add
+for internal mirrors) — without Node it copies the bundled pack itself.
+Prefer **global skills**: `pythia install -g` once per machine serves every
+project, and per-project installs then skip the skills step automatically —
+one copy anywhere means no skill ever shows up twice in the agent's menu. Skills alone: `npx skills add
 thaildhe172591/pythia`, or `/plugin marketplace add thaildhe172591/pythia`.
 
 `pip install` is **once per machine**; `pythia install` is **once per
@@ -92,6 +93,15 @@ project** — run it in each repo's root to drop the skills and a fresh
 project you are standing in (searched upward from the current directory,
 no global fallback), so one global CLI never mixes up databases.
 
+**Updating** follows the same split:
+
+```bash
+pip install --upgrade pythia-plsql   # new CLI version (once per machine)
+pythia install                       # refresh a project's skills; config never touched
+```
+
+(`npx skills update` also works for skills installed via npx.)
+
 Running from a clone works too — `python scripts/pythia.py <command>`; every
 printed follow-up command matches how you invoked it. Windows, macOS, Linux
 and WSL are all CI-tested.
@@ -121,12 +131,18 @@ every agent read them first (`pythia conventions` shows both).
 
 **The account is the real security layer** — the policy file is an application-side
 fence. Give the agent its own revocable credential with proxy authentication
-(`agent_user[schema_owner]`, no `ANY` privileges, no owner password shared).
-`pythia agent-user` generates that SQL for your current connection — password
-included, `--save` drops the credential into `connections.json` — but it is
-optional convenience: running
+(`agent_user[schema_owner]`, no `ANY` privileges, no owner password shared):
+
+```bash
+pythia agent-user --save   # SQL for the DBA + matching credential saved as <conn>_agent
+pythia check               # after the DBA ran it: proxy session, warning gone
+```
+
+One run does both — the password is regenerated each run, so the SQL and the
+saved config must come from the same run. Optional convenience: doing it by
+hand with
 [`examples/agent-user-setup.example.sql`](examples/agent-user-setup.example.sql)
-by hand works just as well.
+works just as well.
 `pythia check` warns when the session runs with more power than the task needs.
 
 Per-group write policy, `.pythia/policy.json` (defaults shown):

{pythia_plsql-0.2.0 → pythia_plsql-0.3.0}/skills/pythia-apply/SKILL.md

@@ -21,6 +21,16 @@ Applies to every write: new objects, fixes, restores, batch runs. No
 exceptions for "trivial" changes — a one-line change can invalidate twelve
 dependents.
 
+Three moves are FORBIDDEN for agents, and the CLI enforces the first two
+(no terminal attached → refusal):
+
+- `--yes` — it is the developer's flag, never yours.
+- `pythia policy set <group>` to anything LOOSER — loosening policy is the
+  developer's decision; hand them the exact command to run themselves.
+- Passing `--confirm` in the same turn as the preview. The preview ends
+  your turn; the token is only used after the developer's approval
+  arrives as a NEW message.
+
 ## The Workflow
 
 **Before step 1:** if this conversation has not yet seen a standalone impact

{pythia_plsql-0.2.0 → pythia_plsql-0.3.0}/skills/pythia-setup/SKILL.md

@@ -41,8 +41,15 @@ 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]"`.
+Run `pythia agent-user --save` — ONE run, in the project directory. It
+prints the three-statement proxy SQL with a generated password and saves
+the matching credential as connection `<conn>_agent` (the new default; the
+owner entry stays untouched). The password is regenerated on every run, so
+never preview first and save later — the SQL and the saved config must
+come from the same run. Relay the SQL to the developer verbatim for a DBA
+to execute, then verify with `pythia check`. `--json` gives the same
+result machine-readable. Manual alternative:
+`examples/agent-user-setup.example.sql`, names adapted.
 
 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_plsql-0.2.0 → pythia_plsql-0.3.0}/skills/pythia-write/SKILL.md

@@ -40,6 +40,14 @@ existing ones — not to introduce a better style.
    `reference/patterns.md` — cursor and bulk patterns, exception discipline,
    bind variables, commit ownership.
 
+## Scope is the developer's sentence, not yours
+
+Change ONLY the objects the developer named. When impact shows dependents
+that will break, you REPORT them with the list and a proposal — fixing
+them is a separate request that needs its own explicit approval. "While I
+was there" is how an asked-for table edit becomes seven unasked procedure
+rewrites.
+
 ## Conventions outrank preferences
 
 If the codebase writes explicit cursors where you would write `FOR r IN`,

{pythia_plsql-0.2.0 → pythia_plsql-0.3.0}/tests/test_install.py

@@ -35,11 +35,11 @@ def test_scaffold_creates_config_once_and_never_clobbers():
 
 
 def test_missing_npx_falls_back_to_the_bundled_pack():
-    """No Node -> the whole kit still installs. One target only
-    (.agents/skills, the universal layout) — a second copy in
-    .claude/skills would double every skill in Claude Code's menu. The
-    copy merges: foreign skills survive, and stale plsql-* copies of the
-    pack's old names are cleaned from both conventional roots."""
+    """No Node -> the whole kit still installs, into .claude/skills ONLY —
+    the directory Claude Code reliably reads (field evidence: project
+    .agents/skills is invisible to some versions, and any second copy
+    doubles every menu entry). Foreign skills survive; stale plsql-* and
+    old .agents pack copies are cleaned."""
     import shutil
     old = shutil.which
     shutil.which = lambda name: None
@@ -50,36 +50,39 @@ def test_missing_npx_falls_back_to_the_bundled_pack():
     with tempfile.TemporaryDirectory() as td:
         agents = pathlib.Path(td) / ".agents" / "skills"
         claude = pathlib.Path(td) / ".claude" / "skills"
-        # pre-existing content: a custom skill, and stale old-name copies
         (agents / "my-team-skill").mkdir(parents=True)
         (agents / "my-team-skill" / "SKILL.md").write_text("x", encoding="utf-8")
-        (agents / "plsql-apply").mkdir()
+        (agents / "pythia-apply").mkdir()      # stale copy from 0.2.0-0.2.3
         (claude / "plsql-review").mkdir(parents=True)
         targets = pythia.copy_bundled_skills(td)
-        assert targets == [agents]
-        assert (agents / "pythia-apply" / "SKILL.md").is_file()
-        assert (agents / "pythia-review" / "reference" / "antipatterns.md").is_file()
-        assert not (claude / "pythia-apply").exists()      # single target
+        assert targets == [claude]
+        assert (claude / "pythia-apply" / "SKILL.md").is_file()
+        assert (claude / "pythia-review" / "reference" / "antipatterns.md").is_file()
+        assert not (agents / "pythia-apply").exists()       # single copy
         assert (agents / "my-team-skill" / "SKILL.md").read_text(
-            encoding="utf-8") == "x"                        # merge, not wipe
-        assert not (agents / "plsql-apply").exists()        # legacy cleaned
-        assert not (claude / "plsql-review").exists()       # in both roots
-        pythia.copy_bundled_skills(td)                      # idempotent
-
-
-def test_invocation_names_the_dash_m_form():
-    """`python -m pythia` runs with argv[0] = a site-packages path nobody
-    typed; the printed follow-ups must use the -m form instead."""
-    import types
-    real_main = sys.modules.get("__main__")
-    fake = types.ModuleType("__main__")
-    fake.__spec__ = types.SimpleNamespace(name="pythia")
-    sys.modules["__main__"] = fake
-    try:
-        interp = pathlib.Path(sys.executable).stem
-        assert pythia.invocation() == f"{interp} -m pythia"
-    finally:
-        sys.modules["__main__"] = real_main
+            encoding="utf-8") == "x"                         # merge, not wipe
+        assert not (claude / "plsql-review").exists()        # legacy cleaned
+        pythia.copy_bundled_skills(td)                       # idempotent
+
+
+def test_global_pack_detection_skips_project_copies():
+    with tempfile.TemporaryDirectory() as home:
+        assert not pythia.global_pack_present(home)
+        d = pathlib.Path(home) / ".claude" / "skills" / "pythia-apply"
+        d.mkdir(parents=True)
+        (d / "SKILL.md").write_text("x", encoding="utf-8")
+        assert pythia.global_pack_present(home)
+
+
+def test_skills_add_cmd_scopes():
+    """Unattended project installs pin one agent (no double-install);
+    global installs use -g; the interactive picker stays untouched."""
+    assert pythia.skills_add_cmd("npx", "o/r", interactive=False) == \
+        ["npx", "skills", "add", "o/r", "-y", "-a", "claude-code"]
+    assert pythia.skills_add_cmd("npx", "o/r", interactive=False, glob=True) == \
+        ["npx", "skills", "add", "o/r", "-g", "-y"]
+    assert pythia.skills_add_cmd("npx", "o/r", interactive=True) == \
+        ["npx", "skills", "add", "o/r"]
 
 
 def test_pack_dirs_resolve_in_the_source_layout():
@@ -87,6 +90,38 @@ def test_pack_dirs_resolve_in_the_source_layout():
     assert (pythia.SKILLS_DIR / "pythia-apply" / "SKILL.md").is_file()
 
 
+def test_agent_user_json_saves_the_same_password_it_prints():
+    """The agent flow: one --json --save run must be self-consistent — the
+    password inside the SQL is the password written to connections.json."""
+    import argparse
+    import contextlib
+    import io
+    import os
+    with tempfile.TemporaryDirectory() as td:
+        root = pathlib.Path(td)
+        (root / ".pythia").mkdir()
+        (root / ".pythia" / "connections.json").write_text(json.dumps(
+            {"dev": {"host": "h", "port": 1521, "service_name": "s",
+                     "user": "OWNER", "password": "p", "schema": "OWNER"}}),
+            encoding="utf-8")
+        cwd = os.getcwd()
+        os.chdir(td)
+        try:
+            ns = argparse.Namespace(conn=None, json=True, save=True, name=None)
+            buf = io.StringIO()
+            with contextlib.redirect_stdout(buf):
+                pythia.cmd_agent_user(None, None, ns)
+            d = json.loads(buf.getvalue())
+            assert d["saved_connection"] == "dev_agent"
+            assert d["password"] in d["sql"]
+            cfg = json.loads((root / ".pythia" / "connections.json")
+                             .read_text(encoding="utf-8"))
+            assert cfg["dev_agent"]["password"] == d["password"]
+            assert cfg["dev"]["password"] == "p"        # owner untouched
+        finally:
+            os.chdir(cwd)
+
+
 def test_one_version_across_every_manifest():
     """pyproject, plugin.json, marketplace.json and npm/package.json must all
     carry the same version — the release workflow publishes from one tag."""

{pythia_plsql-0.2.0 → pythia_plsql-0.3.0}/tests/test_phase1.py

@@ -254,8 +254,7 @@ def test_to_unistr():
 
 
 def test_agent_user_sql_is_least_privilege():
-    sql = pythia.AGENT_USER_SQL.format(owner="APP", agent="APP_AGENT",
-                                       password="x")
+    sql = pythia.agent_user_sql("APP", "APP_AGENT", "x", exists=False)
     assert "CREATE USER APP_AGENT" in sql
     assert "GRANT CREATE SESSION TO APP_AGENT" in sql
     assert "GRANT CONNECT THROUGH APP_AGENT" in sql

{pythia_plsql-0.2.0 → pythia_plsql-0.3.0}/tests/test_phase3.py

@@ -8,6 +8,9 @@ import pathlib
 import sys
 import tempfile
 
+import os
+os.environ.setdefault("PYTHIA_CI", "1")   # the suites are headless by design
+
 sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent.parent / "scripts"))
 import pythia  # noqa: E402
 
@@ -558,6 +561,103 @@ def test_journal_prune_keeps_applied_entries():
         assert pythia.list_journal_entries(td) == [kept]
 
 
+def test_agent_user_alter_form_and_warning_prediction():
+    """DB-aware agent-user: an existing agent user gets the ALTER+UNLOCK
+    form (CREATE would be ORA-01920), and a dirty owner is called out —
+    check will STILL warn — before the DBA runs anything."""
+    import argparse
+    import contextlib
+    import io
+    import os
+    script = {"from all_users": ([("USERNAME",)], [("APP_AGENT",)]),
+              "from session_privs": ([("PRIVILEGE",)], [("DROP ANY TABLE",)])}
+    with tempfile.TemporaryDirectory() as td:
+        (pathlib.Path(td) / ".pythia").mkdir()
+        (pathlib.Path(td) / ".pythia" / "connections.json").write_text(
+            json.dumps({"dev": {"host": "h", "user": "APP", "password": "p",
+                                "schema": "APP"}}), encoding="utf-8")
+        cwd = os.getcwd()
+        os.chdir(td)
+        try:
+            ns = argparse.Namespace(conn=None, json=True, save=False, name=None)
+            buf = io.StringIO()
+            with contextlib.redirect_stdout(buf):
+                pythia.cmd_agent_user(FakeConn(script), "APP", ns)
+            d = json.loads(buf.getvalue())
+        finally:
+            os.chdir(cwd)
+        assert d["agent_user_exists"] is True
+        assert "ALTER USER APP_AGENT IDENTIFIED BY" in d["sql"]
+        assert "ACCOUNT UNLOCK" in d["sql"]
+        assert "CREATE USER" not in d["sql"]
+        assert d["check_will_warn"] is True
+        assert d["owner_dangerous_privs"] == ["DROP ANY TABLE"]
+
+
+class _NoTTY:
+    """A headless agent session: PYTHIA_CI cleared, stdin not a terminal."""
+    def __enter__(self):
+        import io
+        self.ci = os.environ.pop("PYTHIA_CI", None)
+        self.stdin = sys.stdin
+        sys.stdin = io.StringIO()
+        return self
+
+    def __exit__(self, *a):
+        sys.stdin = self.stdin
+        if self.ci is not None:
+            os.environ["PYTHIA_CI"] = self.ci
+        return False
+
+
+def test_headless_yes_is_refused_before_anything_is_written():
+    """--yes belongs to a human at a terminal. An agent (no TTY) must be
+    told to preview, stop, and wait for the developer — and nothing may
+    reach the database."""
+    with tempfile.TemporaryDirectory() as td, _NoTTY():
+        conn = FakeConn(base_script())
+        try:
+            pythia.run_apply(conn, "APP", apply_ns(td, file="f.sql", yes=True),
+                             NEW_FILE)
+        except SystemExit as e:
+            msg = str(e)
+            assert "developer" in msg and "--confirm" in msg
+            assert "PYTHIA_CI" in msg
+        else:
+            raise AssertionError("expected SystemExit, none raised")
+        assert wrote_ddl(conn) == []          # refused before the write
+    # the developer at a real terminal keeps --yes (simulated via PYTHIA_CI)
+    with tempfile.TemporaryDirectory() as td:
+        conn = FakeConn(base_script())
+        assert pythia.run_apply(conn, "APP",
+                                apply_ns(td, file="f.sql", yes=True),
+                                NEW_FILE) == 0
+
+
+def test_headless_policy_loosening_is_refused_tightening_allowed():
+    import argparse
+    import contextlib
+    import io
+
+    def policy_ns(root, group, value):
+        return argparse.Namespace(action="set", group=group, value=value,
+                                  json=False, project_root=root)
+
+    with tempfile.TemporaryDirectory() as td, _NoTTY():
+        # deny -> confirm is loosening: the developer's decision
+        try:
+            pythia.cmd_policy(None, None, policy_ns(td, "structural", "confirm"))
+        except SystemExit as e:
+            assert "developer" in str(e) and "policy set structural" in str(e)
+        else:
+            raise AssertionError("expected SystemExit, none raised")
+        assert not pythia.policy_path(td).is_file()   # nothing written
+        # confirm -> deny is tightening: always allowed, even headless
+        with contextlib.redirect_stdout(io.StringIO()):
+            pythia.cmd_policy(None, None, policy_ns(td, "plsql_source", "deny"))
+        assert pythia.load_policy(td)["plsql_source"][0] == "deny"
+
+
 def main():
     failed = 0
     for name, fn in sorted(globals().items()):