docs: modernize + LLM.md + cross-links (one-way SDK model)

LLM.md

@@ -1,53 +1,35 @@
-# Hanzo Python SDK
+# LLM.md — hanzoai/python-sdk
 
-uv workspace. `uv sync --all-packages`; `uv run pytest tests/ -v`.
+**What this is:** the flagship, most-complete Hanzo SDK — a `uv` workspace of 60+
+packages: the typed cloud client (`hanzoai`), agents, MCP server + tools, memory,
+distributed compute, and the `hanzo` CLI. `pip install hanzo`.
 
-## Packages
+**Canonical role (one-way SDK model):** Hanzo ships two SDK lines per language —
+(1) the full cloud SDK generated from OpenAPI, (2) the AI/agents library. This repo
+is the Python flagship of line 2, the reference for every other language.
+Completeness: Python → Rust → C++ → Go. One impl, one place; discovery repos link
+OUT, never duplicate. Full spec: `~/work/hanzo/SDK-ARCHITECTURE.md`.
 
-- **Core:** `hanzoai` (API client) · `hanzo-mcp` (MCP server — thin wrapper that
-  discovers tools via `[project.entry-points."hanzo.tools"]`) · `hanzo-memory` ·
-  `hanzo-repl` · `hanzo-agent`.
-- **Tools** (each exports a `TOOLS` list via its entry point):
-  `hanzo-tools-{shell,browser,fs,memory,reasoning,agent,api,lsp,refactor,llm,…}`.
-
-```
-hanzo-mcp  ──entry points──►  hanzo-tools-*   (each: a TOOLS list)
+## Install / run
+```bash
+pip install hanzo            # CLI + agents + MCP + client
+uv sync --all-packages       # dev: whole workspace
+uv run pytest tests/ -v      # tests
 ```
 
-## Browser tools (hanzo-tools-browser) — zapd consumer
+## Brand rules (hard — enforce in all docs)
+- Never "LLM gateway"; never position against LiteLLM. Hanzo is a full AI SDK / AI
+  cloud, not a proxy.
+- Zen models are our own family — never name upstream models.
+- Paths are `/v1/…`, never `/api/…`. Base host: `https://api.hanzo.ai`.
+- Voice: "Hanzo — the Open AI Cloud." Crisp, developer-first, no emoji-spam.
 
-hanzo-mcp hosts **no** server. It connects to the shared local router
-`~/.zap/run/zapd.sock` (see `~/work/zap`) as a *consumer*, lists providers, and routes
-opaque CDP to a `browser:*` provider (the real Chrome/Firefox extension via its native
-host). No in-process server, no mDNS, no port pool, no HTTP bridge, no Playwright
-fallback in native-browser mode.
+## Key entry points
+- `pkg/hanzoai/` — typed OpenAPI client (`ApiClient`, `Configuration`, `Ai*Api`).
+- `pkg/hanzo/src/hanzo/cli.py` — the `hanzo` CLI command tree.
+- `pkg/hanzo-mcp/` — MCP server; tools via `[project.entry-points."hanzo.tools"]`.
+- `pkg/hanzo-tools-*/` — one concern each, exports a `TOOLS` list.
+- `pkg/hanzo-{agents,agent,network,memory}/` — agent/compute/memory libraries.
 
-```python
-from hanzo_tools.browser.zapd_consumer import get_consumer
-c = get_consumer()                          # ~/.zap/run/zapd.sock
-c.resolve_browser("chrome", None)           # -> browser:chrome/<host>/default
-c.route(provider, "Target.getTargets", {})  # opaque command, raw result bytes
-```
-
-Two tools, one transport: `browser` (high-level verbs) + `cdp` (raw CDP method by
-name). Files: `zapd_consumer.py` (envelope codec + consumer), `browser_tool.py`,
-`cdp_tool.py`. Unit-tested in `tests/test_browser_tools.py` (zapd mocked) + against a
-live zapd; the router (`zap-proto/zapd`) owns the transport tests.
-
-`hanzo-mcp` pins `hanzo-tools-browser[playwright]>=0.5.8` (the zapd-consumer version);
-the Claude Code MCP entry sources it from disk via
-`uvx --from pkg/hanzo-mcp --with-editable pkg/hanzo-tools-browser`.
-
-## Memory
-SQLite + optional vector (sqlite-vec). `~/.hanzo/{memory,db}` global, `.hanzo/` per
-project. Backends: local (default), sqlite, lancedb, kuzu.
-
-## API tool (hanzo-tools-api)
-Generic REST over OpenAPI specs (`~/work/hanzo/openapi/`). Auto-detects `GITHUB_TOKEN`,
-`OPENAI_API_KEY`, etc. `api(action="list|config|call|spec|ops", provider=…)`. Hanzo
-providers: `hanzo`, `hanzo-iam`, `hanzo-gateway`, `hanzo-commerce`, `hanzo-vector`,
-`hanzo-cloud`, `hanzo-nexus`.
-
-## Common issues
-Import error → `uv sync --all-packages`. Missing tool → check the entry point in the
-package's `pyproject.toml`. Backend unavailable → install the optional dep.
+**Rules for agents:** update THIS file with significant discoveries; never write
+random summary files; keep the README cross-link block intact.