fix(skill): address ClawHub security audit findings (#49)

docs/README.md

@@ -53,7 +53,7 @@ root and links here for anything beyond install + quickstart.
 
 ## Advanced
 
-- [Escape hatches](advanced/escape-hatches.md) — `huly api` and
+- [Direct SDK and HTTP access](advanced/direct-access.md) — `huly api` and
   `huly ws` for raw RPCs
 - [CLI architecture](advanced/architecture.md) — source layout,
   connection flow, markup handling

docs/advanced/architecture.md

@@ -115,7 +115,7 @@ warning to stderr, and — if `HULY_MARKDOWN_FALLBACK_FAIL=1` is set
 prosemirror-JSON directly.
 
 For rich-text round-trip features (mention nodes, embeds) that
-don't survive the JSON round-trip, use the raw escape hatch with a
+don't survive the JSON round-trip, use the raw direct SDK access with a
 direct transaction object. The `params` argument is a JSON array
 containing a single `TxCreateDoc` transaction object.
 
@@ -150,7 +150,7 @@ huly ws tx '[{
 }]'
 ```
 
-See [Escape hatches — WebSocket (`huly ws`)](escape-hatches.md#websocket-huly-ws)
+See [Direct SDK and HTTP access — WebSocket (`huly ws`)](direct-access.md#websocket-huly-ws)
 for the full RPC contract. The `tx` RPC accepts every transaction
 type — `TxCreateDoc`, `TxUpdateDoc`, `TxRemoveDoc`, `TxMixin`,
 `TxApplyIf` — with the same JSON shape as the `core:class:*`

docs/advanced/direct-access.md

@@ -0,0 +1,84 @@
+---
+title: Direct SDK and HTTP access (advanced)
+description: When huly-cli doesn't have a flag for what you need — `huly api` and `huly ws` for raw, unvalidated passthroughs against your self-hosted Huly workspace. Advanced use only.
+---
+
+# Direct SDK and HTTP access (advanced)
+
+> **Advanced only.** Two commands bypass every CLI safety check — ref resolution, type checking, cascade awareness, error mapping, and (for destructive calls) confirmation prompts:
+>
+> - **`huly api`** — raw HTTP passthrough.
+> - **`huly ws`** — raw WebSocket RPC.
+>
+> Treat them like raw SQL. Most workflows do not need them. If you find yourself reaching for them often for a pattern the CLI should expose, file an issue — that's a missing-feature signal.
+
+When a CLI command doesn't exist for what you need, or the flag you need isn't exposed, talk to the server directly. Both commands are pass-through — they don't filter or transform the response.
+
+## Table of contents
+
+- [HTTP (`huly api`)](#http-huly-api)
+- [WebSocket (`huly ws`)](#websocket-huly-ws)
+- [When to use direct SDK access](#when-to-use-direct-sdk-access)
+
+---
+
+## HTTP (`huly api`)
+
+```bash
+huly api GET /api/v1/version
+huly api GET /config.json
+huly api POST /api/v1/something --body '{"key":"value"}'
+huly api GET /api/v1/things --query foo=bar --query baz=qux
+huly api GET /api/v1/things --header "Authorization: Bearer ..."
+```
+
+Available methods: `GET | POST | PUT | PATCH | DELETE`. The path
+is appended to the workspace's API URL. The CLI does not validate the path, method, body, or any custom headers — anything you send goes straight to the server.
+
+> **`Authorization` is not overridable.** The CLI always sets `Authorization: Bearer <resolved-token>` after merging your custom headers (`packages/cli/src/raw/api.ts:43-49`), so passing `--header "Authorization: Bearer …"` has no effect. All other custom headers pass through verbatim.
+
+---
+
+## WebSocket (`huly ws`)
+
+The Huly RPC protocol uses WebSocket for the SDK connection, but the
+raw `huly ws` command is **text JSON only**. Use it for direct
+method calls without opening the SDK's binary transport:
+
+```bash
+# findAll
+huly ws findAll '[{"_class":"tracker:class:Project"},{}]'
+
+# tx (raw transaction)
+huly ws tx '[{"_class":"core:class:TxCreateDoc",...}]'
+```
+
+> `huly ws` accepts a single positional `<method>` followed by an
+> optional `[params]` argument that is a **JSON-encoded array of
+> positional parameters** for that method. On Huly 0.7.x the raw
+> socket dispatches a small whitelist: `findAll`, `tx`, `hello`, and
+> `ping`. Do not rely on `findOne`, `createDoc`, `updateDoc`, or other
+> SDK methods through this command — use the high-level commands
+> for writes, or `tx` for raw transaction payloads.
+>
+> The `tx` RPC supports every transaction type — `TxCreateDoc`,
+> `TxUpdateDoc`, `TxRemoveDoc`, `TxMixin`, `TxApplyIf`. Build the
+> payload directly; the CLI doesn't validate. **Confirm with the user before invoking** — raw RPC has no CLI confirmation prompt and bypasses every safety check.
+
+---
+
+## When to use direct SDK access
+
+- A command exists but doesn't expose the flag you need (rare). Use the high-level command with `--set key=value` first; reach for `huly ws` / `huly api` only when the field is not exposed at all.
+- A command exists but operates on a wrong sub-resource.
+- You're debugging and need to see the raw server response.
+- The CLI doesn't support the surface you need (use the SDK
+  instead — see
+  [Migration — from the SDK](../guides/migration.md#from-the-huly-sdk-typescript)).
+
+The commands pass through directly; the CLI handles auth and
+caching, not transformation. If you find yourself reaching for
+`huly ws` often, that's a signal the CLI should expose that surface
+natively — file an issue.
+
+**Do not use raw RPC to bypass `--yes`, validation, or duplicate-identifier checks.** Those refusals are intentional.

docs/advanced/server-architecture.md

@@ -151,7 +151,7 @@ For self-hosted single-pod deployments, use `WS_OPERATION=all+backup`.
 ## The WebSocket protocol
 
 The SDK connection speaks Huly's binary RPC protocol over WebSocket.
-The CLI's raw `huly ws` escape hatch is a separate **text-JSON**
+The CLI's raw `huly ws` direct SDK access is a separate **text-JSON**
 channel — the two are different transports to the transactor. Key
 methods on the binary SDK side:
 

docs/guides/migration.md

@@ -136,7 +136,7 @@ error formatting. Prefer the CLI for one-off scripts; prefer the SDK
 for long-running services.
 
 If you need to call a method the CLI doesn't expose, see
-[Escape hatches](../advanced/escape-hatches.md) for `huly ws` (raw
+[Direct SDK and HTTP access](../advanced/direct-access.md) for `huly ws` (raw
 WebSocket RPC).
 
 ---
@@ -156,7 +156,7 @@ huly api GET /api/v1/version
 The CLI's `api` command passes through to the REST API but handles
 auth headers automatically. Use it for ad-hoc endpoints the CLI
 doesn't cover. See
-[Escape hatches — HTTP (`huly api`)](../advanced/escape-hatches.md#http-huly-api).
+[Direct SDK and HTTP access — HTTP (`huly api`)](../advanced/direct-access.md#http-huly-api).
 
 ---
 

docs/reference/environment.md

@@ -148,7 +148,7 @@ huly ws findAll '[{"_class":"core.class.Tx"},{"objectId":"<doc-id>","modifiedOn"
 
 Each tx carries `modifiedBy`, `modifiedOn`, `space`, `objectId`,
 and the full operations payload. See
-[Escape hatches — WebSocket (`huly ws`)](../advanced/escape-hatches.md#websocket-huly-ws).
+[Direct SDK and HTTP access — WebSocket (`huly ws`)](../advanced/direct-access.md#websocket-huly-ws).
 
 ---
 

docs/reference/model.md

@@ -7,7 +7,7 @@ description: Huly class IDs and plugin-to-CLI mapping — the canonical referenc
 
 Class IDs and plugin-to-CLI mapping. The CLI's canonical class IDs
 live in `src/transport/identifiers.ts` — that's the reference for
-escape-hatch use ([`huly ws findAll ...`](../advanced/escape-hatches.md#websocket-huly-ws)).
+direct SDK access use ([`huly ws findAll ...`](../advanced/direct-access.md#websocket-huly-ws)).
 
 ## Table of contents
 
@@ -21,7 +21,7 @@ escape-hatch use ([`huly ws findAll ...`](../advanced/escape-hatches.md#websocke
 ## Class ID reference
 
 The platform's class hierarchy. Used as `_class` in JSON, as class
-IDs in escape-hatch calls, and as class filters in queries.
+IDs in direct SDK access calls, and as class filters in queries.
 
 | Plugin         | Class ID pattern       | Examples                                                                                                             |
 | -------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------- |