sql-harness 0.3.3__tar.gz → 0.3.5__tar.gz

{sql_harness-0.3.3 → sql_harness-0.3.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sql-harness
-Version: 0.3.3
+Version: 0.3.5
 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
@@ -15,6 +15,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Database
 Classifier: Topic :: System :: Shells
 Requires-Python: >=3.12
+Requires-Dist: markdown-it-py<4,>=3
 Requires-Dist: paramiko<4,>=3.4
 Requires-Dist: psycopg[binary]<4,>=3.2
 Requires-Dist: pymysql<2,>=1.1
@@ -37,7 +38,7 @@ uv sync
 uv run sql-harness init
 
 # 3. Add a connection
-uv run sql-harness add local_pg --driver postgres --url 'postgresql://postgres:postgres@localhost:5432/postgres'
+uv run sql-harness add --name local_pg --driver postgres --url 'postgresql://postgres:postgres@localhost:5432/postgres'
 
 # 4. Test it
 uv run sql-harness test local_pg
@@ -49,6 +50,9 @@ print(query("SELECT version()"))
 print(list_tables())
 print(describe("pg_class"))
 PY
+
+# 6. Browse + edit the docs (SKILL.md, interaction-skills/, your zone skills)
+uv run sql-harness web
 ```
 
 ## Architecture (~1k lines across 8 core files)

{sql_harness-0.3.3 → sql_harness-0.3.5}/SKILL.md

@@ -7,7 +7,7 @@ description: "Always use sql-harness for SQL, SSH, and database operations — q
 
 A single-process SQL + SSH CLI for agents. 5 drivers (`postgres`, `mysql`, `sqlite`, `redis`, `ssh`) share one heredoc namespace. Connections live in plaintext in one TOML file.
 
-For setup, read `install.md`. For stuck-point mechanics, see `interaction-skills/` (cross-DB) and `interaction-skills/postgres/` (PG depth).
+For setup, read `install.md` (shipped next to this file; in a source checkout it's `docs/install.md`). For stuck-point mechanics, see `interaction-skills/` (cross-DB) and `interaction-skills/postgres/` (PG depth).
 
 ## Reach for sql-harness when...
 
@@ -26,9 +26,9 @@ For setup, read `install.md`. For stuck-point mechanics, see `interaction-skills
 ```bash
 sql-harness --help
 sql-harness list
-sql-harness add <name> --driver postgres --url 'postgresql://user:pw@host/db'
-sql-harness add <name> --driver mysql   --url 'mysql+pymysql://user:pw@host/db'
-sql-harness add <name> --driver ssh     --url 'ssh://user@host:22?key=/path/id_ed25519'
+sql-harness add --name <name> --driver postgres --url 'postgresql://user:pw@host/db'
+sql-harness add --name <name> --driver mysql    --url 'mysql+pymysql://user:pw@host/db'
+sql-harness add --name <name> --driver ssh      --url 'ssh://user@host:22?key=/path/id_ed25519'
 sql-harness test <name>
 
 sql-harness <<'PY'
@@ -42,7 +42,7 @@ PY
 - **First call requires `use_workspace(name)`** — no implicit default.
 - Set `BH_SQL_ZONE_SKILLS=1` once so `use_workspace()` auto-surfaces that zone's per-DSN skill docs (see `interaction-skills/zone-skill-auto-surface.md`).
 - For task-specific helpers, drop them into `agent-workspace/zones/<conn>/helpers.py` and they merge into the heredoc namespace (per-zone, overriding the shared base).
-- Other subcommands: `init` (scaffold connections.toml + install preset zone skills), `doctor` (SELECT 1 on every connection), `edit`/`remove`/`show`, `workspace {list,use,close,show}`, `save`/`run`/`scripts`, `skill` (bare: emit packaged SKILL.md; `install`/`list`/`show`), `paths`, `open`, `stats`, `version`, `ssh {exec,upload,download,run-script,info}`.
+- Other subcommands: `init` (scaffold connections.toml + install preset zone skills), `doctor` (SELECT 1 on every connection), `edit`/`remove`/`show`, `workspace {list,use,close,show}`, `save`/`run`/`scripts`, `skill` (bare: emit packaged SKILL.md; `install`/`list`/`show`), `paths`, `open`, `web` (browse + edit the whole doc library in a local web UI — shipped docs, runtime zones, saved scripts), `stats`, `version`, `ssh {exec,upload,download,run-script,info}`.
 - Zone-scoped subcommands (`save`, `run`, `scripts`, `skill list/show`, `ssh`) need `-c <conn>` or `$BH_SQL_ACTIVE_CONNECTION`.
 - **Analytics (ON by default)**: every CLI call and every doc read (`apply_skill`, `skill`, `skill show`) is counted into `$BH_SQL_HOME/analytics.json`; view with `sql-harness stats`. Every executed command (CLI argv or heredoc body) plus failures is appended to `$BH_SQL_HOME/sql-harness.log` (NDJSON, one record per line). Disable both with `BH_SQL_ANALYTICS=0|off|false|no`. Extension point: `from sql_harness.analytics import on, CLI_INVOKED, DOC_READ, COMMAND_EXECUTED` to attach custom listeners (observer pattern).
 
@@ -71,7 +71,7 @@ Standard SQLAlchemy + PyMySQL. JSON syntax differs from PG — see `interaction-
 
 ### SQLite (`sqlite:///path.db`)
 
-Local dev / tests. All standard helpers work. Use `sql-harness add --driver sqlite --url 'sqlite:///<absolute-path>'` (SQLite needs absolute path).
+Local dev / tests. All standard helpers work. Use `sql-harness add --name <name> --driver sqlite --url 'sqlite:///<absolute-path>'` (SQLite needs absolute path).
 
 ### Redis (`redis://host:port`)
 
@@ -103,7 +103,7 @@ See `interaction-skills/ssh/` for: `ssh.md` (helpers + CLI + gotchas), `docker-v
 | `list_tables(schema=None)` | `list[str]` | Schema recon — always start here |
 | `describe(table, schema=None)` | `list[dict]` | Columns + types — before writing SQL |
 | `table(name, schema=None, limit=None)` | `list[dict]` | Quick peek: `SELECT * FROM x LIMIT n` |
-| `with_transaction()` | context manager yielding `Connection` | ≥ 2 statements / DDL / atomicity |
+| `with_transaction()` | context manager yielding `Connection` | ≥ 2 DML statements / atomicity (DDL: PG+SQLite only) |
 | `run_sql_file(path)` | `list[dict]` | Multi-statement `.sql`, one transaction |
 | `server_version()` | `str` | Round-trip liveness check |
 | `connection_info()` | `dict` | Current workspace metadata |
@@ -159,7 +159,8 @@ Reached via `apply_skill("pool")` etc. from any active zone — `zones/meta/skil
 
 - **Start with `list_tables` + `describe`, not `query`.** Before writing SQL on an unknown DB, run `list_tables(schema=None)` then `describe("table", schema=None)` to learn the columns. Skips the trial-and-error SELECT cycle.
 - **Set `BH_SQL_ZONE_SKILLS=1` once** so every `use_workspace()` surfaces that zone's per-DSN skill docs as a hint list (10 filenames max). Then `apply_skill(name)` reads the body when relevant.
-- **Default to `with_transaction()`** for any write with ≥ 2 statements (insert + update, drop + create, …). Atomic + automatic rollback on exception.
+- **Default to `with_transaction()`** for any write with ≥ 2 statements (insert + update, update + delete, …). Automatic rollback on exception — **for DML**. DDL is a different story: PostgreSQL and SQLite roll back `CREATE`/`DROP`/`ALTER` inside a transaction, **MySQL does not** (it implicitly commits), so a `drop + create` migration that fails halfway leaves you with neither table. Run DDL migrations with a backup or a reversible plan, not on the strength of the transaction. See `interaction-skills/migrations.md`.
+- **Transactions are only real on a transactional engine.** A MySQL table created on a server whose `@@default_storage_engine` is not InnoDB (e.g. MyISAM) ignores `ROLLBACK` *silently* — the write sticks and nothing warns you. Check with `SELECT @@default_storage_engine`, and write `ENGINE=InnoDB` explicitly if you need rollback.
 - **For PG performance tasks, reach for the 8 PG-only helpers first** (`explain_analyze`, `slow_queries`, `unused_indexes`, `seq_scan_heavy`, `table_stats`, `index_usage_stats`, `missing_indexes_hint`). Don't hand-parse `pg_stat_*` SQL.
 - **For remote tasks, reach for SSH workspace first.** Don't reach for raw `subprocess` + ssh-key files in agent code — `ssh_exec("systemctl restart myapp")` is one line.
 - **For "insert returning the new id"**: psycopg supports `INSERT … RETURNING id`; MySQL has no `RETURNING` — use `execute(...)` and read `result.lastrowid`.
@@ -189,6 +190,29 @@ Reached via `apply_skill("pool")` etc. from any active zone — `zones/meta/skil
 - For tables > 10k rows, use `engine.connect().execution_options(stream_results=True)` and iterate manually — `query()` loads everything into memory.
 - SSH SFTP subsystem may be disabled on the remote host. `ssh_upload/ssh_download` raise `RuntimeError("SFTP subsystem not available")`; fall back to `tar -czf - | ssh host tar -xzf -` via `ssh_exec`.
 - Default `ssh_exec` timeout is 30 s. Long-running commands (e.g. `pg_dump`, `tar czf`) need explicit `timeout=`.
+- **Long output is spilled to a file, not printed.** A failed run whose traceback is long, and any `ssh exec` / `ssh run-script` output past a few KB, are written to `$BH_SQL_HOME/tmp/output/` and replaced by a pointer line naming the path, line count and size. That is deliberate — read the file when you actually need it. `BH_SQL_TRACEBACK=1` forces the raw traceback to stderr instead. The full traceback always also lands in `$BH_SQL_HOME/sql-harness.log` (NDJSON), whatever the terminal shows.
+
+## Read-only connections (`read_only = true`)
+
+For a sensitive database, mark the connection read-only. Two rails are installed at the driver layer, both attached to the **engine** rather than to `query()`/`execute()` — so `conn.execute()`, `run_sql_file()` and any path that skips the helpers are covered too.
+
+```toml
+[[connections]]
+name = "prod_ro"
+driver = "mysql"
+url = "mysql+pymysql://ro_user@host:3306/proddb"
+read_only = true
+```
+
+```bash
+sql-harness add --name prod_ro --driver mysql --url '...' --read-only
+```
+
+What it refuses: anything whose verb is not `SELECT`/`SHOW`/`DESCRIBE`/`EXPLAIN`/`TABLE`/`VALUES`/`PRAGMA`, plus transaction control. **Unrecognised statements are refused, not permitted** — that is why it is an allow-list: a deny-list misses `CALL`, `DO`, `LOAD DATA`, `HANDLER` and every future statement type. It also handles the dodges a naive keyword match falls for: `/*!50000 DROP */` (MySQL executes those), `SELECT 1; DROP TABLE t`, `WITH x AS (...) DELETE`, `EXPLAIN ANALYZE DELETE` (PostgreSQL executes it), and `#` — which is a comment in MySQL but the XOR operator in PostgreSQL, so treating it as a comment there would hide a write. On MySQL it additionally refuses `INTO OUTFILE`/`INTO DUMPFILE`/`FOR UPDATE`/`LOCK IN SHARE MODE`; on PostgreSQL, `SELECT ... INTO` (creates a table) and the `FOR ...` lock variants.
+
+Where the backend has a session setting, it is applied on **every new pooled connection**: `SET SESSION TRANSACTION READ ONLY` (MySQL) / `SET SESSION CHARACTERISTICS AS TRANSACTION READ ONLY` (PostgreSQL). That rail is enforced by the server, so it catches anything that slips past the statement guard (e.g. a stored procedure).
+
+**This is a guard rail, not a security boundary.** Both rails are escapable from the same session — a caller can run `SET SESSION TRANSACTION READ WRITE` and carry on, and any client-side check is pattern matching rather than a parser. The only hard boundary is the database account: use `GRANT SELECT ON db.* TO ...` for a database you genuinely must not write to, and treat everything above as defence in depth on top of it. SQLite has no session rail at all; for a file database the real boundary is the URL (`sqlite:///file:path?mode=ro&uri=true`). SSH workspaces ignore the flag — a remote shell is not a statement stream.
 
 ## Domain / table skills
 

{sql_harness-0.3.3 → sql_harness-0.3.5}/docs/AGENTS.md

@@ -12,12 +12,15 @@ Core code lives in `lab/sql_harness/src/sql_harness/`:
 - `config.py` — TOML schema + ConnectionConfig / ConnectionsConfig dataclasses
 - `paths.py` — XDG-style state directory resolution
 - `drivers/` — backend abstractions (postgres, mysql, redis stub, sqlite for tests)
+- `drivers/readonly.py` — read-only statement guard shared by the SQL drivers: comment/literal-stripping, allow-list verb check, and `install_guard()` which attaches both rails to an engine. Read its module docstring before relying on it — it is a guard rail, not a security boundary
 - `manager.py` — SqlHarness class: holds engines, workspaces, skills registry
 - `helpers.py` — heredoc helpers (auto-imported)
 - `agent_loader.py` — loads `$BH_SQL_AGENT_WORKSPACE/agent_helpers.py`
 - `analytics.py` — event bus (observer) + JSON stats + NDJSON execution log: CLI call counts, doc-read tracking, command/error history; `BH_SQL_ANALYTICS` (default ON), view with `sql-harness stats`
+- `output.py` — terminal output policy: UTF-8 stream setup, long-output spill to `$BH_SQL_HOME/tmp/output/`, concise error rendering; `BH_SQL_TRACEBACK=1` forces raw tracebacks
+- `webapp.py` — `sql-harness web`: serves the doc library (shipped docs + runtime zones + saved scripts) over loopback with an in-page editor. `resolve_doc()` is the write boundary — read its docstring before touching path handling
 - `run.py` — heredoc entry; delegates to CLI otherwise
-- `cli.py` — argparse subparser CLI (18 subcommands)
+- `cli.py` — argparse subparser CLI (19 subcommands)
 
 `SKILL.md` tells agents how to use the harness.
 `docs/install.md` tells agents how to install and configure it.

{sql_harness-0.3.3 → sql_harness-0.3.5}/docs/README.md

@@ -14,7 +14,7 @@ uv sync
 uv run sql-harness init
 
 # 3. Add a connection
-uv run sql-harness add local_pg --driver postgres --url 'postgresql://postgres:postgres@localhost:5432/postgres'
+uv run sql-harness add --name local_pg --driver postgres --url 'postgresql://postgres:postgres@localhost:5432/postgres'
 
 # 4. Test it
 uv run sql-harness test local_pg
@@ -26,6 +26,9 @@ print(query("SELECT version()"))
 print(list_tables())
 print(describe("pg_class"))
 PY
+
+# 6. Browse + edit the docs (SKILL.md, interaction-skills/, your zone skills)
+uv run sql-harness web
 ```
 
 ## Architecture (~1k lines across 8 core files)

{sql_harness-0.3.3/skills/sql-harness/references → sql_harness-0.3.5/docs}/install.md

@@ -27,7 +27,8 @@ Writes `~/.config/sql-harness/connections.toml` (or `$BH_SQL_HOME/connections.to
 ## 3. Add your first connection
 
 ```bash
-uv run sql-harness add my_pg \
+uv run sql-harness add \
+    --name my_pg \
     --driver postgres \
     --url 'postgresql://user:pw@localhost:5432/db' \
     --description "My dev DB"
@@ -89,7 +90,9 @@ password = "${env:IOT_SSH_PASSWORD}"  # standalone secret — keeps the URL clea
 
 `${env:VAR}` placeholders inside `url` and `password` are expanded at load time from the process environment — keep prod secrets out of the file.
 
-Optional per-connection keys: `description`, `password`, `pool_size`, `pool_recycle`, `pre_ping`, `echo`, `application_name`.
+Optional per-connection keys: `description`, `password`, `read_only`, `pool_size`, `pool_recycle`, `pre_ping`, `echo`, `application_name`.
+
+`read_only = true` refuses writes on that connection — a statement allow-list on every statement the engine sends, plus the server-side session read-only setting where the backend has one. Use it for sensitive databases, but note it is a **guard rail, not a security boundary**: the session setting is escapable from the same session, and any client-side check is pattern matching. Pair it with a `SELECT`-only database account, which is the actual boundary. See `SKILL.md` → "Read-only connections".
 
 SSH password precedence (highest first): password embedded in `url` > the `password` key > `$BH_SSH_PASSWORD`. A connection that sets a password uses password auth exclusively — local `~/.ssh` keys are not consulted (see `interaction-skills/ssh/auth-and-tunnels.md`).
 

{sql_harness-0.3.3 → sql_harness-0.3.5}/docs/maintainer.md

@@ -17,14 +17,26 @@ hand-synced copies. `pyproject.toml` `[tool.hatch.build.targets.wheel.force-incl
 maps the repo docs into the wheel:
 
 - `SKILL.md` → `sql_harness/_skills/SKILL.md`
+- `docs/install.md` → `sql_harness/_skills/install.md`
 - `interaction-skills` → `sql_harness/_skills/interaction-skills`
 - `agent-workspace/zones/meta/skills` → `sql_harness/_skills/zones-meta-skills`
 
 The root `SKILL.md` is the **single source of truth** (v0.3.0 consolidation —
 the old `skills/sql-harness/SKILL.md` and `src/sql_harness/SKILL.md` copies
-were removed). After editing it, just `uv build` again. `sql-harness skill`
-reads `sql_harness/_skills/SKILL.md` from the installed package and falls
-back to the repo-root `SKILL.md` in a source checkout.
+were removed; v0.3.4 removed the last hand-synced copy,
+`skills/sql-harness/references/install.md`). After editing it, just
+`uv build` again. `sql-harness skill` reads `sql_harness/_skills/SKILL.md`
+from the installed package and falls back to the repo-root `SKILL.md` in a
+source checkout.
+
+`SKILL.md` references `install.md` as a sibling file — that only resolves
+because `docs/install.md` is force-included into the bundle as
+`_skills/install.md`. Dropping it from the force-include list breaks the
+reference for every `skill install` user.
+
+`skill install` needs a real (non-editable) wheel install to work: it reads
+`sql_harness/_skills/`, which only exists after `uv build`. In a bare source
+checkout `_bundled_skills_root()` returns `None` and the command exits 2.
 
 ## Build outputs
 
@@ -44,7 +56,7 @@ The wheel contains the package modules + the `_skills/` doc bundle
 ```bash
 # standalone venv
 uv sync
-uv run pytest tests/unit -q    # 80 tests must pass
+uv run pytest tests/unit -q    # 133 tests must pass
 uv run sql-harness --help      # CLI works
 uv run sql-harness skill       # SKILL.md emit works
 ```

{sql_harness-0.3.3 → sql_harness-0.3.5}/interaction-skills/transactions.md

@@ -55,3 +55,4 @@ for attempt in range(3):
 - `text("SELECT ...").execution_options(...)` is per-statement; transaction-level options belong on the `SET` line.
 - Nested `with_transaction()` will create a SAVEPOINT (PostgreSQL) or fail (MySQL). Don't nest.
 - A failed statement inside a transaction does NOT auto-rollback the whole transaction in some dialects — call `conn.rollback()` explicitly if you've swallowed the exception.
+- **A non-transactional table ignores `ROLLBACK` silently.** On MySQL, check `SELECT @@default_storage_engine` before trusting a rollback: if it is not InnoDB, any table created without an explicit `ENGINE=InnoDB` accepts `BEGIN`/`ROLLBACK` and discards them — the row is still there afterwards and nothing errors. Reach for `with_transaction()` on such tables and you get the *appearance* of atomicity with none of the substance.

{sql_harness-0.3.3 → sql_harness-0.3.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sql-harness"
-version = "0.3.3"
+version = "0.3.5"
 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 = "docs/README.md"
 license = { text = "MIT" }
@@ -24,6 +24,7 @@ dependencies = [
     "pymysql>=1.1,<2",
     "sqlalchemy>=2.0,<3",
     "paramiko>=3.4,<4",
+    "markdown-it-py>=3,<4",
 ]
 
 [project.scripts]
@@ -38,6 +39,10 @@ sql-harness = "sql_harness.run:main"
 requires = ["hatchling"]
 build-backend = "hatchling.build"
 
+[[tool.uv.index]]
+url = "https://pypi.tuna.tsinghua.edu.cn/simple"
+default = true
+
 [tool.hatch.build.targets.wheel]
 # Mirrors browser-harness's setuptools src-layout. The package source is
 # under `src/sql_harness/`; the package name (top-level import) is `sql_harness`.
@@ -50,6 +55,7 @@ packages = ["src/sql_harness"]
 # shipping its SKILL.md in the wheel, but extended to the whole doc bundle.
 # Paths are relative to this pyproject.toml (lab/sql_harness/).
 "SKILL.md" = "sql_harness/_skills/SKILL.md"
+"docs/install.md" = "sql_harness/_skills/install.md"
 "interaction-skills" = "sql_harness/_skills/interaction-skills"
 "agent-workspace/zones/meta/skills" = "sql_harness/_skills/zones-meta-skills"
 

sql_harness-0.3.5/src/sql_harness/_web/app.css

@@ -0,0 +1,191 @@
+/* sql-harness doc browser — docs-site styling, no framework. */
+
+:root {
+  --bg: #ffffff;
+  --bg-soft: #f6f7f9;
+  --bg-side: #fafbfc;
+  --fg: #1f2328;
+  --fg-soft: #59636e;
+  --fg-faint: #818b98;
+  --line: #d8dee4;
+  --line-soft: #eaeef2;
+  --accent: #0969da;
+  --accent-soft: #ddf4ff;
+  --danger: #cf222e;
+  --ok: #1a7f37;
+  --code-bg: #f6f8fa;
+  --radius: 6px;
+  --mono: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace;
+  --sans: -apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans", Helvetica, Arial, sans-serif;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg: #0d1117; --bg-soft: #161b22; --bg-side: #0f141b;
+    --fg: #e6edf3; --fg-soft: #9198a1; --fg-faint: #6e7681;
+    --line: #30363d; --line-soft: #21262d;
+    --accent: #4493f8; --accent-soft: #121d2f;
+    --danger: #f85149; --ok: #3fb950; --code-bg: #161b22;
+  }
+}
+
+* { box-sizing: border-box; }
+
+html, body {
+  margin: 0; height: 100%;
+  background: var(--bg); color: var(--fg);
+  font-family: var(--sans); font-size: 15px; line-height: 1.65;
+}
+
+.app { display: flex; height: 100vh; }
+
+/* --- sidebar --- */
+.sidebar {
+  width: 310px; flex: 0 0 310px; height: 100vh;
+  display: flex; flex-direction: column;
+  background: var(--bg-side); border-right: 1px solid var(--line);
+}
+.brand {
+  display: flex; align-items: baseline; gap: 8px;
+  padding: 16px 18px 12px; font-weight: 600;
+}
+.brand-name { font-size: 15px; letter-spacing: -0.01em; }
+.brand-ver { font-size: 12px; color: var(--fg-faint); font-weight: 400; }
+
+.filter {
+  margin: 0 12px 10px; padding: 7px 10px;
+  border: 1px solid var(--line); border-radius: var(--radius);
+  background: var(--bg); color: var(--fg); font-size: 13px; font-family: inherit;
+}
+.filter:focus { outline: none; border-color: var(--accent); }
+
+.nav { flex: 1; overflow-y: auto; padding: 0 8px 24px; }
+.group-title {
+  padding: 14px 10px 6px; font-size: 11px; font-weight: 600;
+  text-transform: uppercase; letter-spacing: 0.06em; color: var(--fg-faint);
+}
+.root-title {
+  display: flex; align-items: center; gap: 6px;
+  padding: 5px 10px; font-size: 13px; font-weight: 600; color: var(--fg-soft);
+}
+.badge {
+  font-size: 10px; font-weight: 500; padding: 1px 5px; border-radius: 20px;
+  background: var(--accent-soft); color: var(--accent);
+}
+.count { margin-left: auto; font-size: 11px; color: var(--fg-faint); font-weight: 400; }
+
+.nav details { margin: 0; }
+.nav summary {
+  cursor: pointer; list-style: none; padding: 3px 10px 3px 22px;
+  font-size: 13px; color: var(--fg-soft); border-radius: var(--radius);
+}
+.nav summary::-webkit-details-marker { display: none; }
+.nav summary::before { content: "▸ "; color: var(--fg-faint); font-size: 10px; }
+.nav details[open] > summary::before { content: "▾ "; }
+.nav summary:hover { background: var(--bg-soft); }
+
+.nav a {
+  display: block; padding: 3px 10px 3px 34px;
+  font-size: 13px; color: var(--fg-soft); text-decoration: none;
+  border-radius: var(--radius); overflow: hidden;
+  text-overflow: ellipsis; white-space: nowrap;
+}
+.nav a:hover { background: var(--bg-soft); color: var(--fg); }
+.nav a.active { background: var(--accent-soft); color: var(--accent); font-weight: 500; }
+.nav .empty { padding: 2px 10px 2px 34px; font-size: 12px; color: var(--fg-faint); }
+
+.sidebar-foot {
+  padding: 10px 18px; border-top: 1px solid var(--line-soft);
+  font-size: 12px; color: var(--fg-faint); display: flex; align-items: center; gap: 6px;
+}
+.dot { width: 7px; height: 7px; border-radius: 50%; background: var(--ok); }
+.dot.ro { background: var(--fg-faint); }
+
+/* --- content --- */
+.content { flex: 1; display: flex; flex-direction: column; min-width: 0; }
+
+.doc-head {
+  display: flex; align-items: center; gap: 12px;
+  padding: 12px 32px; border-bottom: 1px solid var(--line-soft);
+  position: sticky; top: 0; background: var(--bg); z-index: 5;
+}
+.crumb {
+  font-family: var(--mono); font-size: 12px; color: var(--fg-faint);
+  overflow: hidden; text-overflow: ellipsis; white-space: nowrap; flex: 1;
+}
+.actions { display: flex; gap: 8px; flex: 0 0 auto; }
+.actions button {
+  padding: 5px 12px; font-size: 13px; font-family: inherit;
+  border: 1px solid var(--line); border-radius: var(--radius);
+  background: var(--bg-soft); color: var(--fg); cursor: pointer;
+}
+.actions button:hover { border-color: var(--fg-faint); }
+.actions button.primary { background: var(--accent); border-color: var(--accent); color: #fff; }
+.actions button.primary:hover { filter: brightness(1.08); }
+.actions button:disabled { opacity: 0.5; cursor: default; }
+
+.markdown, .editor { flex: 1; overflow-y: auto; }
+.markdown { padding: 28px 32px 80px; max-width: 860px; }
+.editor {
+  margin: 0; padding: 20px 24px; border: none; resize: none;
+  background: var(--code-bg); color: var(--fg);
+  font-family: var(--mono); font-size: 13px; line-height: 1.6;
+}
+.editor:focus { outline: none; }
+
+/* --- metadata panel --- */
+.meta {
+  margin: 20px 32px -8px; padding: 12px 16px;
+  border: 1px solid var(--line); border-left: 3px solid var(--accent);
+  border-radius: var(--radius); background: var(--bg-soft);
+  font-size: 13px; max-width: 860px;
+}
+.meta dl { margin: 0; display: grid; grid-template-columns: 90px 1fr; gap: 4px 12px; }
+.meta dt { color: var(--fg-faint); font-family: var(--mono); font-size: 12px; }
+.meta dd { margin: 0; color: var(--fg-soft); word-break: break-word; }
+
+/* --- status line --- */
+.status {
+  padding: 8px 32px; font-size: 13px; border-top: 1px solid var(--line-soft);
+  background: var(--bg-soft);
+}
+.status.err { color: var(--danger); }
+.status.ok { color: var(--ok); }
+
+/* --- markdown --- */
+.markdown h1, .markdown h2, .markdown h3, .markdown h4 {
+  line-height: 1.3; margin: 1.6em 0 0.6em; font-weight: 600; letter-spacing: -0.01em;
+}
+.markdown h1 { font-size: 1.9em; margin-top: 0; padding-bottom: 0.3em; border-bottom: 1px solid var(--line-soft); }
+.markdown h2 { font-size: 1.4em; padding-bottom: 0.25em; border-bottom: 1px solid var(--line-soft); }
+.markdown h3 { font-size: 1.15em; }
+.markdown p, .markdown ul, .markdown ol { margin: 0.85em 0; }
+.markdown ul, .markdown ol { padding-left: 1.6em; }
+.markdown li { margin: 0.25em 0; }
+.markdown a { color: var(--accent); text-decoration: none; }
+.markdown a:hover { text-decoration: underline; }
+.markdown code {
+  font-family: var(--mono); font-size: 0.87em;
+  background: var(--code-bg); padding: 0.15em 0.4em; border-radius: 4px;
+}
+.markdown pre {
+  background: var(--code-bg); padding: 14px 16px; border-radius: var(--radius);
+  overflow-x: auto; border: 1px solid var(--line-soft);
+}
+.markdown pre code { background: none; padding: 0; font-size: 12.5px; line-height: 1.55; }
+.markdown blockquote {
+  margin: 0.9em 0; padding: 0 1em; color: var(--fg-soft);
+  border-left: 3px solid var(--line);
+}
+.markdown table {
+  border-collapse: collapse; margin: 1em 0; display: block; overflow-x: auto; max-width: 100%;
+}
+.markdown th, .markdown td { border: 1px solid var(--line); padding: 6px 12px; text-align: left; }
+.markdown th { background: var(--bg-soft); font-weight: 600; }
+.markdown hr { border: none; border-top: 1px solid var(--line-soft); margin: 2em 0; }
+
+@media (max-width: 820px) {
+  .app { flex-direction: column; }
+  .sidebar { width: 100%; flex: 0 0 45vh; height: 45vh; border-right: none; border-bottom: 1px solid var(--line); }
+  .markdown, .doc-head, .status, .meta { padding-left: 16px; padding-right: 16px; margin-left: 0; margin-right: 0; }
+}