sql-harness 0.2.2__tar.gz → 0.2.3__tar.gz

{sql_harness-0.2.2 → sql_harness-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sql-harness
-Version: 0.2.2
+Version: 0.2.3
 Summary: Single-process SQL + SSH CLI for LLM agents. PostgreSQL/MySQL/SSH via SQLAlchemy + paramiko. Plaintext credentials in one TOML file. Helpers auto-injected into the heredoc namespace.
 Project-URL: Source, https://github.com/zhaoliuxue/much_bigpy/tree/master/lab/sql_harness
 Project-URL: Issues, https://github.com/zhaoliuxue/much_bigpy/issues
@@ -58,7 +58,8 @@ PY
 - `lab/sql_harness/src/sql_harness/` — protected core package
 - `${XDG_CONFIG_HOME:-~/.config}/sql-harness/connections.toml` — plaintext credentials in ONE place
 - `${XDG_CONFIG_HOME:-~/.config}/sql-harness/agent-workspace/agent_helpers.py` — task-specific helpers
-- `${XDG_CONFIG_HOME:-~/.config}/sql-harness/agent-workspace/skills/` — per-task/per-table skills
+- `${XDG_CONFIG_HOME:-~/.config}/sql-harness/agent-workspace/zones/<conn>/skills/` — per-DSN skills (one zone per connection)
+- `${XDG_CONFIG_HOME:-~/.config}/sql-harness/agent-workspace/zones/meta/skills/` — cross-DSN strategy skills (passive fallback for `apply_skill`)
 
 ## Why mirror browser-harness?
 
@@ -78,7 +79,7 @@ PY
 
 PRs and improvements welcome. See `AGENTS.md` for code priorities.
 
-- **Skills are written by the harness, not by you.** When you figure out a non-obvious SQL flow (a weird schema, a slow query, a JSON column trick), file a skill in `agent-workspace/skills/<name>.md`. Future sessions will read it before re-discovering it.
+- **Skills are written by the harness, not by you.** When you figure out a non-obvious SQL flow (a weird schema, a slow query, a JSON column trick), file a skill in `agent-workspace/zones/<conn>/skills/<name>.md` for that DSN, or `agent-workspace/zones/meta/skills/<name>.md` if it generalizes. Future sessions will read it before re-discovering it.
 - Bug fixes, new drivers, helper additions all welcome.
 
 ## License

{sql_harness-0.2.2 → sql_harness-0.2.3}/README.md

@@ -35,7 +35,8 @@ PY
 - `lab/sql_harness/src/sql_harness/` — protected core package
 - `${XDG_CONFIG_HOME:-~/.config}/sql-harness/connections.toml` — plaintext credentials in ONE place
 - `${XDG_CONFIG_HOME:-~/.config}/sql-harness/agent-workspace/agent_helpers.py` — task-specific helpers
-- `${XDG_CONFIG_HOME:-~/.config}/sql-harness/agent-workspace/skills/` — per-task/per-table skills
+- `${XDG_CONFIG_HOME:-~/.config}/sql-harness/agent-workspace/zones/<conn>/skills/` — per-DSN skills (one zone per connection)
+- `${XDG_CONFIG_HOME:-~/.config}/sql-harness/agent-workspace/zones/meta/skills/` — cross-DSN strategy skills (passive fallback for `apply_skill`)
 
 ## Why mirror browser-harness?
 
@@ -55,7 +56,7 @@ PY
 
 PRs and improvements welcome. See `AGENTS.md` for code priorities.
 
-- **Skills are written by the harness, not by you.** When you figure out a non-obvious SQL flow (a weird schema, a slow query, a JSON column trick), file a skill in `agent-workspace/skills/<name>.md`. Future sessions will read it before re-discovering it.
+- **Skills are written by the harness, not by you.** When you figure out a non-obvious SQL flow (a weird schema, a slow query, a JSON column trick), file a skill in `agent-workspace/zones/<conn>/skills/<name>.md` for that DSN, or `agent-workspace/zones/meta/skills/<name>.md` if it generalizes. Future sessions will read it before re-discovering it.
 - Bug fixes, new drivers, helper additions all welcome.
 
 ## License

{sql_harness-0.2.2 → sql_harness-0.2.3}/SKILL.md

@@ -58,14 +58,12 @@ PG optimization depth — `interaction-skills/postgres/`:
 - `interaction-skills/postgres/specialized-indexes.md`
 - `interaction-skills/postgres/table-optimization.md`
 
-## Workspace / strategy skills
+## Cross-DSN strategy skills
 
-Read these when working across multiple connections, tuning pool behavior, or operating remote hosts:
+Read these when working across multiple connections, tuning pool behavior, or operating remote hosts. Reached via `apply_skill("pool")` etc. from any active zone — `zones/meta/skills/` is the passive fallback layer (the legacy global `agent-workspace/skills/` was collapsed into a regular zone so `apply_skill()` has a single shape: active zone or meta).
 
-- `agent-workspace/skills/pool.md` — pool sizing, `pre_ping`, idle reuse.
-- `agent-workspace/skills/workspace.md` — workspace isolation, multi-DB workflows.
-- `agent-workspace/skills/ssh.md` — strategy for hitting remote DB hosts over SSH.
-- `agent-workspace/skills/docker-deploy.md` — strategy: when to use docker-via-ssh, the `~/sql-harness/<svc>/` cohesion convention, service catalog (coturn/mysql/redis/...).
+- `agent-workspace/zones/meta/skills/pool.md` — pool sizing, `pre_ping`, idle reuse.
+- `agent-workspace/zones/meta/skills/workspace.md` — workspace isolation, multi-DB workflows.
 
 ## What actually works (field-tested)
 
@@ -98,4 +96,4 @@ Read these when working across multiple connections, tuning pool behavior, or op
 
 ## Domain / table skills
 
-PG optimization practice: `practice/pgexercises/` (71 pgexercises problems, see its README). Per-table or per-schema skills: drop a markdown file into `agent-workspace/skills/<name>.md`, read with `apply_skill(name)`.
+PG optimization practice: `practice/pgexercises/` (71 pgexercises problems, see its README). Per-table or per-schema skills: drop a markdown file into `agent-workspace/zones/<conn>/skills/<name>.md`, read with `apply_skill(name)`. Cross-DSN strategy goes to `zones/meta/skills/` instead.

{sql_harness-0.2.2 → sql_harness-0.2.3}/interaction-skills/docker-via-ssh.md

@@ -130,8 +130,7 @@ Those live in `docker-services/coturn/README.md` — read before deploying cotur
 
 ## See also
 
-- `agent-workspace/skills/docker-deploy.md` — strategy (when to use this pattern,
-  service catalog, why `~/sql-harness/<svc>/` convention)
+- This file's "Detection" / "Approach" sections (decision P: the legacy strategy stub in `agent-workspace/zones/meta/skills/docker-deploy.md` was collapsed into the mechanic; no separate doc).
 - `interaction-skills/ssh.md` — the raw ssh_exec/upload/download helpers
 - `docker-services/<svc>/` — shipped templates (coturn, mysql, redis, ...)
 - `docker-services/<svc>/README.md` — service-specific gotchas (e.g. coturn)

{sql_harness-0.2.2 → sql_harness-0.2.3}/interaction-skills/ssh.md

@@ -1,6 +1,6 @@
 # SSH mechanic — how to talk to an SSH workspace
 
-> **Mechanic guide.** For the strategy (when to use it, auth choice), see `agent-workspace/skills/ssh.md`.
+> **Mechanic guide.** Strategy notes (when to reach for the SSH driver, auth choice) are folded into this file's "Detection" / "Approach" sections below (decision P: the legacy strategy stub was collapsed into the mechanic).
 
 ## Activation
 

{sql_harness-0.2.2 → sql_harness-0.2.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sql-harness"
-version = "0.2.2"
+version = "0.2.3"
 description = "Single-process SQL + SSH CLI for LLM agents. PostgreSQL/MySQL/SSH via SQLAlchemy + paramiko. Plaintext credentials in one TOML file. Helpers auto-injected into the heredoc namespace."
 readme = "README.md"
 license = { text = "MIT" }
@@ -52,7 +52,7 @@ artifacts = ["src/sql_harness/SKILL.md"]
 # Paths are relative to this pyproject.toml (lab/sql_harness/).
 "SKILL.md" = "sql_harness/_skills/SKILL.md"
 "interaction-skills" = "sql_harness/_skills/interaction-skills"
-"agent-workspace/skills" = "sql_harness/_skills/agent-workspace-skills"
+"agent-workspace/zones/meta/skills" = "sql_harness/_skills/zones-meta-skills"
 # Docker service templates (coturn/mysql/redis/...) — the docker-via-ssh mechanic
 # uploads these to ~/sql-harness/<svc>/ on a remote host.
 "docker-services" = "sql_harness/_skills/docker-services"

{sql_harness-0.2.2 → sql_harness-0.2.3}/src/sql_harness/__init__.py

@@ -7,11 +7,16 @@ agent-editable workspace. Connections live in plaintext in one TOML file
 
 from __future__ import annotations
 
+try:
+    from importlib.metadata import version as _pkg_version
+except Exception:
+    _pkg_version = None  # type: ignore
+
 from .config import ConnectionConfig, ConnectionsConfig, PoolConfig, load, save
 from .drivers import Driver, get_driver
 from .manager import SqlHarness, Workspace
 
-__version__ = "0.1.0"
+__version__ = _pkg_version("sql-harness") if _pkg_version else "0.0.0+local"
 
 __all__ = [
     "ConnectionConfig",

{sql_harness-0.2.2 → sql_harness-0.2.3}/src/sql_harness/cli.py

@@ -289,29 +289,27 @@ def cmd_skill(args, _harness: SqlHarness) -> int:
     if code:
         return code
     if sub == "list":
-        d = zone_skills_dir(conn)
-        zone = d.glob("*.md") if d.is_dir() else []
-        # Also include global skills (shipped examples) as fallback.
-        global_d = workspace_dir() / "skills"
-        global_ = global_d.glob("*.md") if global_d.is_dir() else []
-        seen = set()
-        names = []
-        for p in sorted(zone) + sorted(global_):
-            if p.stem not in seen:
-                seen.add(p.stem)
-                names.append(p.stem)
+        seen: set[str] = set()
+        names: list[str] = []
+        # Two-layer lookup: active zone wins, zones/meta supplies cross-DSN fallback.
+        for d in (zone_skills_dir(conn), zone_skills_dir("meta")):
+            if d.is_dir():
+                for p in sorted(d.glob("*.md")):
+                    if p.stem not in seen:
+                        seen.add(p.stem)
+                        names.append(p.stem)
         _emit({"connection": conn, "skills": names})
         return 0
     if sub == "show":
         zone_path = zone_skills_dir(conn) / f"{args.name}.md"
-        global_path = workspace_dir() / "skills" / f"{args.name}.md"
+        meta_path = zone_skills_dir("meta") / f"{args.name}.md"
         if zone_path.is_file():
             print(zone_path.read_text(encoding="utf-8"))
-        elif global_path.is_file():
-            print(global_path.read_text(encoding="utf-8"))
+        elif meta_path.is_file():
+            print(meta_path.read_text(encoding="utf-8"))
         else:
             print(
-                f"error: no skill named {args.name!r} in zone {conn!r} or global",
+                f"error: no skill named {args.name!r} in zone {conn!r} or zones/meta",
                 file=sys.stderr,
             )
             return 2
@@ -331,8 +329,13 @@ def _package_root_dir() -> Path:
 
 
 def _shipped_skills_dir() -> Path:
-    """Shipped preset skills: <root>/agent-workspace/skills/."""
-    return _package_root_dir() / "agent-workspace" / "skills"
+    """Shipped preset (cross-DSN) skills source: zones/meta/skills/.
+
+    `sql-harness init` copies every .md under this dir into the runtime
+    workspace's zones/meta/skills/ so `apply_skill()` can find them as
+    fallback from any active zone.
+    """
+    return _package_root_dir() / "agent-workspace" / "zones" / "meta" / "skills"
 
 
 def _packaged_skill_body() -> str | None:
@@ -487,9 +490,12 @@ def cmd_init(_args, _harness: SqlHarness) -> int:
     else:
         _emit({"path": str(path), "existed": True})
 
-    target_skills = workspace_dir() / "skills"
-    ensure_private_dir(target_skills)
-    copied = _copy_shipped_skills(target_skills)
+    # Shipped cross-DSN strategy skills land in zones/meta/skills/ (decision P:
+    # collapsed the legacy global layer into a regular zone so apply_skill()
+    # has a single shape: zone or meta).
+    target_meta = zone_skills_dir("meta")
+    ensure_private_dir(target_meta)
+    copied = _copy_shipped_skills(target_meta)
     if copied:
         print(
             f"installed {len(copied)} preset skills: {', '.join(copied)}",
@@ -655,7 +661,7 @@ def cmd_paths(args, harness: SqlHarness) -> int:
         _path_record("config_dir", P.config_dir()),
         _path_record("config_file", P.config_file()),
         _path_record("agent_workspace", P.workspace_dir()),
-        _path_record("global_skills", P.workspace_dir() / "skills"),
+        _path_record("meta_skills", P.zone_skills_dir("meta")),
         _path_record("runtime_dir", P.runtime_dir()),
         _path_record("tmp_dir", P.tmp_dir()),
         _path_record("package_root", _package_root_dir()),
@@ -697,7 +703,7 @@ def _resolve_open_path(target: str, conn: str | None) -> Path:
         "home": P.home_dir(),
         "config": P.config_dir(),
         "workspace": P.workspace_dir(),
-        "skills": P.workspace_dir() / "skills",
+        "skills": P.zone_skills_dir("meta"),
         "runtime": P.runtime_dir(),
         "tmp": P.tmp_dir(),
         "package": _package_root_dir(),

{sql_harness-0.2.2 → sql_harness-0.2.3}/src/sql_harness/helpers.py

@@ -311,35 +311,34 @@ def with_transaction():
 # --- Skill / script helpers (per-DSN zone) ---------------------------------
 
 def apply_skill(name: str) -> str:
-    """Read a skill markdown from the ACTIVE connection's zone (or global fallback).
+    """Read a skill markdown from the ACTIVE zone, with zones/meta as fallback.
 
-    Mirrors browser-harness's per-domain skill lookup. Zone wins if present;
-    falls back to the global agent-workspace/skills/ directory so shipped
-    skills (pool.md, workspace.md) remain reachable.
+    Two-layer fallback (decision P): the active zone wins if it has the skill;
+    otherwise zones/meta/skills/ (cross-DSN strategy knowledge, populated by
+    `sql-harness init`) supplies the answer. This collapses the legacy
+    global `agent-workspace/skills/` layer into a regular zone so the lookup
+    is single-shape: zone or meta.
     """
     conn = _require_connection()
     zone_path = paths.zone_skills_dir(conn) / f"{name}.md"
     if zone_path.is_file():
         return zone_path.read_text(encoding="utf-8")
-    # Fallback to global skills dir (shipped examples).
-    global_path = paths.workspace_dir() / "skills" / f"{name}.md"
-    if global_path.is_file():
-        return global_path.read_text(encoding="utf-8")
+    meta_path = paths.zone_skills_dir("meta") / f"{name}.md"
+    if meta_path.is_file():
+        return meta_path.read_text(encoding="utf-8")
     raise FileNotFoundError(
-        f"no skill named {name!r} in zone {conn!r} or global {paths.workspace_dir() / 'skills'}"
+        f"no skill named {name!r} in zone {conn!r} or zones/meta"
     )
 
 
 def list_skills() -> list[str]:
-    """List skills in the ACTIVE connection's zone UNION the global skills dir."""
-    zone = set()
-    d = paths.zone_skills_dir(_require_connection())
-    if d.is_dir():
-        zone.update(p.stem for p in d.glob("*.md"))
-    global_d = paths.workspace_dir() / "skills"
-    if global_d.is_dir():
-        zone.update(p.stem for p in global_d.glob("*.md"))
-    return sorted(zone)
+    """List skills in the ACTIVE zone UNION zones/meta (cross-DSN fallback)."""
+    conn = _require_connection()
+    seen: set[str] = set()
+    for d in (paths.zone_skills_dir(conn), paths.zone_skills_dir("meta")):
+        if d.is_dir():
+            seen.update(p.stem for p in d.glob("*.md"))
+    return sorted(seen)
 
 
 def list_scripts() -> list[str]:

{sql_harness-0.2.2 → sql_harness-0.2.3}/src/sql_harness/paths.py

@@ -47,8 +47,8 @@ def workspace_dir() -> Path:
           - helpers.py          per-connection helpers (merged over the shared base)
           - scripts/<name>.py   saved heredocs for this connection
           - skills/<name>.md    per-connection skill knowledge
+      - zones/meta/skills/      cross-DSN strategy skills (apply_skill fallback)
       - scripts/                (legacy global scripts, pre-zone)
-      - skills/                 (legacy global skills, pre-zone)
     """
     override = os.environ.get("BH_SQL_AGENT_WORKSPACE")
     return Path(override).expanduser() if override else home_dir() / "agent-workspace"

{sql_harness-0.2.2 → sql_harness-0.2.3}/tests/unit/test_cli.py

@@ -190,7 +190,7 @@ def test_paths_lists_global_dirs(tmp_path: Path) -> None:
     data = json.loads(p.stdout)
     names = {r["name"] for r in data["global"]}
     # The key folders a user wants to open must all be present.
-    assert {"home", "config_file", "agent_workspace", "global_skills",
+    assert {"home", "config_file", "agent_workspace", "meta_skills",
             "package_root", "package_source"} <= names
     # config_file should point inside the isolated BH_SQL_HOME.
     cf = next(r for r in data["global"] if r["name"] == "config_file")

{sql_harness-0.2.2 → sql_harness-0.2.3}/tests/unit/test_manager.py

@@ -63,6 +63,10 @@ def test_close_workspace_unknown_is_noop() -> None:
 
 
 def test_skills_no_dir(tmp_path, monkeypatch) -> None:
+    """SqlHarness.apply_skill/list_skills is the legacy class-level API
+    (decision C in the P-plan): it still reads workspace_dir()/skills/ unchanged.
+    The canonical entry is the module-level helpers.py:apply_skill, which uses
+    the zones/meta fallback. See test_helpers.py for the new behavior."""
     monkeypatch.setenv("BH_SQL_AGENT_WORKSPACE", str(tmp_path / "isolated_ws"))
     h = SqlHarness(_sqlite_config())
     assert h.list_skills() == []

{sql_harness-0.2.2 → sql_harness-0.2.3}/uv.lock

@@ -446,7 +446,7 @@ wheels = [
 
 [[package]]
 name = "sql-harness"
-version = "0.2.1"
+version = "0.2.2"
 source = { editable = "." }
 dependencies = [
     { name = "paramiko" },

sql_harness-0.2.2/agent-workspace/skills/README.md

@@ -1,26 +0,0 @@
-# agent-workspace/skills — strategy layer
-
-Strategy-altitude notes for sql-harness: **when** and **why** to reach for a
-pattern. The **how** (helpers, commands, gotchas) lives one level down in
-`interaction-skills/` — these docs point there, they don't duplicate it.
-
-## Files in this folder
-
-- `pool.md` — ships the `[pool_defaults]` block + recycle-timing rule; points at the pooling mechanic for sizing
-- `workspace.md` — one connection = one workspace; isolation, lifecycle, multi-DB, cross-workspace-transaction warning
-- `ssh.md` — when to reach for `driver = "ssh"` vs a DB workspace; auth reference; host-key-trust decision
-- `docker-deploy.md` — when to deploy docker-compose over SSH; service catalog; `~/sql-harness/<svc>/` convention; lifecycle decisions
-
-## When to read which
-
-- Queries stall / connections go stale → `pool.md` (then the pooling mechanic)
-- Juggling >1 database, or "can I share a connection?" → `workspace.md`
-- Need to run shell / move files on a remote box → `ssh.md`
-- Standing up mysql / redis / coturn / nginx on a remote host → `docker-deploy.md`
-
-## When to skip
-
-Most pool / workspace / ssh / docker tuning is **mechanic work** — read
-`interaction-skills/` first (`pooling.md`, `ssh.md`, `docker-via-ssh.md`,
-`transactions.md`). Come here only when a mechanic doc points at strategy, or
-when you're deciding *whether* to use a pattern rather than *how* to run it.

sql_harness-0.2.2/agent-workspace/skills/docker-deploy.md

@@ -1,85 +0,0 @@
-# Docker-via-SSH deployment — strategy
-
-> **Strategy layer** for deploying docker-compose services to remote hosts via
-> sql-harness SSH. For the **mechanic** (upload + `docker compose up` + verify),
-> see `interaction-skills/docker-via-ssh.md`. This doc is about **when**, **why**,
-> and **which service** — the convention, the catalog, the lifecycle decisions.
-
-## When to use this pattern
-
-Use `docker-via-ssh` when:
-
-- You have **1–N remote hosts** (Aliyun ECS, a VPS, a home lab box) reachable by SSH
-- You want **standard services** (mysql / postgres / redis / coturn / nginx / grafana) running, self-contained
-- You want **re-deployable / scriptable** deploys (not manual `docker run` you'll forget)
-- You **don't** need k8s-scale orchestration (no auto-scaling, no multi-node clustering)
-
-Don't use it when:
-
-- You need **multi-node clustering** (Hadoop / HBase across N hosts) → k8s / Nomad
-- The service needs **bare-metal perf** (GPU passthrough, hugepages) → systemd unit
-- You're on a **managed platform** (Aliyun RDS, Redis Cloud) → use the managed one
-
-## The convention: `~/sql-harness/<service>/` on the remote
-
-Every deployed service lives in its own dir under `~/sql-harness/<service>/` **on
-the remote host** — compose + config + data + logs, all with relative mounts
-(`./data`, not absolute paths). The mechanic doc shows the layout tree and the
-relative-mount rationale in full; the strategy payoff is:
-
-| Property | How the convention delivers it |
-|---|---|
-| **Cohesion** | A service's compose + config + data + logs are all in one dir |
-| **Backup** | `tar czf coturn.tgz ~/sql-harness/coturn/` — one command, complete |
-| **Teardown** | `docker compose down && rm -rf ~/sql-harness/<svc>` — clean |
-| **Upgrade** | re-upload compose → `docker compose up -d` (rolling, keeps data) |
-| **Discovery** | `ls ~/sql-harness/` shows what's deployed |
-| **Isolation** | services don't share mounts/networks unless explicitly composed together |
-| **Portability** | relative mounts follow the dir — move or migrate hosts without editing paths |
-
-## Service catalog (shipped templates in `docker-services/`)
-
-| Service | Image | Ports | Use case |
-|---|---|---|---|
-| `coturn` | `coturn/coturn` | 3478, 5349, 49152-65535/udp | WebRTC TURN/STUN (P2P hole-punching) |
-| `mysql` | `mysql:8.0` | 3306 | Relational DB (sql-harness `mysql` driver connects here) |
-| `postgresql` | `postgres:16` | 5432 | Relational DB (sql-harness `postgres` driver connects here) |
-| `redis` | `redis:7-alpine` | 6379 | Cache / KV (sql-harness `redis` driver — when implemented) |
-| `nginx` | `nginx:alpine` | 80, 443 | Reverse proxy / static hosting |
-| `rabbitmq` | `rabbitmq:3-management` | 5672, 15672 | Message queue |
-| `cloud-grafana` | `grafana/grafana` + `prom/prometheus` | 3000, 9090 | Monitoring stack |
-
-Each template in `docker-services/<svc>/` ships a `docker-compose.yml` + config
-files, all with relative mounts. Pick one → the mechanic's 4-step loop uploads
-and starts it. Pair a deployed DB service with a matching **DB workspace**
-(`driver = "mysql"`/`postgres`) to run SQL against it — SSH-level container
-management + DB-level queries on the same host is the typical diagnostic loop.
-
-## Lifecycle decisions
-
-| Question | Answer |
-|---|---|
-| New service? | pick template → upload → `up -d` (4-step loop in mechanic doc) |
-| Image update? | edit compose tag → re-upload → `up -d` (keeps data) |
-| Config change? | edit conf → re-upload → `restart` (or `up -d` if compose changed) |
-| Host migration? | `tar` the service dir → scp to new host → `up -d` |
-| Out of disk? | `docker system prune -af` (careful) + check service `data/` growth |
-| Service flapping? | `docker logs -f` → `docker compose ps` → healthcheck output |
-| Stop paying for it? | `down -v` + `rm -rf ~/sql-harness/<svc>` + snapshot data first |
-
-## Gotchas (strategy-level)
-
-- **One host = one `~/sql-harness/` root**. Multi-host deploys loop the deploy per
-  host — one sql-harness SSH workspace per host.
-- **Don't mount the SAME host port from two services** — mysql + postgres coexist
-  fine on their defaults, but two mysql instances need port remapping.
-- **Healthy ≠ reachable by the DB workspace**: if a container isn't healthy,
-  `sql-harness test <db-workspace>` fails confusingly — check `docker compose ps`
-  before assuming a sql-harness bug. (Per-service startup gotchas live with the
-  mechanic and `docker-services/<svc>/README.md`.)
-
-## See also
-
-- `interaction-skills/docker-via-ssh.md` — the mechanic (layout tree, relative-mount
-  rationale, 4-step deploy loop, per-op lifecycle commands, deploy gotchas)
-- `docker-services/<svc>/` — shipped templates (and `<svc>/README.md` service gotchas)

sql_harness-0.2.2/agent-workspace/skills/ssh.md

@@ -1,70 +0,0 @@
-# SSH workspaces — when to use the SSH driver
-
-> **Strategy guide.** For the mechanics (helper calls, CLI subcommands, SFTP /
-> timeout / quoting gotchas), see `interaction-skills/ssh.md`.
-
-## When to reach for `driver = "ssh"`
-
-Use an SSH workspace to **operate on a remote host** (not a database). It reuses
-the same `use_workspace("name")` abstraction as DB workspaces, but opens a
-paramiko `SSHClient` + SFTP instead of a SQLAlchemy engine — so you get shell +
-file ops with the same ergonomics.
-
-Reach for it to: run ad-hoc shell commands (`ps`, `systemctl`, `cat /var/log/...`);
-do a one-shot deploy / restart / log inspection without a full Ansible playbook;
-upload-then-run a script (`ssh_run_script`); pull a log/artifact down for analysis;
-or pair with a DB workspace (shell check, then `query(...)`).
-
-Don't use it for: heavy interactive shells (no TUI/scrollback/resize — use
-`term-cli` from `lab.subprocess`); long-running daemons (the channel is
-short-lived — use systemd / supervisord); or anything that must survive the
-sql-harness process exit (the connection closes on exit).
-
-## Auth reference
-
-Configure in `connections.toml` (`driver = "ssh"`, `url = "ssh://user@host:port"`).
-Pick an auth strategy:
-
-| Strategy | When | Example URL |
-|---|---|---|
-| SSH key (preferred) | CI / dev boxes with `~/.ssh/id_*` | `ssh://user@host` (auto-resolves key) |
-| Explicit key path | Specific key per connection | `ssh://user@host?key=/opt/keys/prod.pem` |
-| Password | Quick lab use; NOT for prod | `ssh://user:pw@host` (works but key is better) |
-| `ssh+password://` | Force password (no key lookup) | `ssh+password://user:pw@host` |
-| `ssh+key://` | Force key-only auth (no password fallback) | `ssh+key://user@host?key=/path` |
-
-Key resolution order (first hit wins): (1) `?key=...` in the URL, (2) `$BH_SSH_KEY`
-env var, (3) `~/.ssh/id_ed25519` → `id_rsa` → `id_ecdsa`, (4) password from URL or
-`$BH_SSH_PASSWORD`.
-
-## Workspace lifecycle parity
-
-SSH workspaces follow the **same** lazy-open / cached / dispose pattern as DB
-workspaces: `use_workspace("prod-app")` opens TCP+SSH+shell+SFTP and caches it;
-re-opening returns the cached handle for free; process exit / `dispose()` /
-`close_workspace(name)` tears it down.
-
-## Combining with DB workspaces
-
-SSH and DB workspaces are independent — keep one of each open at once. The typical
-diagnostic flow: shell-level process check, then in-process DB check.
-
-```python
-ssh_use_workspace("prod-app")
-print(ssh_exec("ps aux | grep postgres | head -3")["stdout"])
-
-use_workspace("prod_pg")
-print(query("SELECT count(*) FROM pg_stat_activity")["count"])
-```
-
-## Safety — the host-key-trust decision
-
-The driver trusts host keys on first connect (`AutoAddPolicy()`, like
-`StrictHostKeyChecking=accept-new`). Fine for trusted networks; for hostile ones,
-harden this in a subclass. Also prefer a non-root user, and set an explicit
-`timeout=` for long commands. (Connection pooling, shell-vs-exec, path handling,
-non-ASCII decoding and other operational gotchas live in the mechanic doc.)
-
-## See also
-
-- `interaction-skills/ssh.md` — the mechanic (helpers, CLI, SFTP/timeout/quoting gotchas)