docs: add HTTP/auth/SSH/API reference guides and fix tool reference inaccuracies

[laserduor]

Summary

Four documentation improvements for the DBHub docs site, covering previously undocumented configuration surfaces and fixing factual inaccuracies in the tool reference. All changes are docs-only — no source code touched.

Changes

1. New: HTTP Server deployment guide (docs/config/http-server.mdx)

Why: --transport=http has been a first-class feature since the HTTP transport landed, but there was no dedicated page explaining it. The only mention lived inside the CLI reference. Operators deploying DBHub behind a reverse proxy (or running it in Docker) had to piece together the endpoint list, auth model, and security properties from code.

What it covers:

• When to use HTTP vs stdio transport
• Full endpoint reference (/mcp, /healthz, /api/*)
• Security: DNS-rebinding protection, bearer token auth, CORS
• Production deployment: reverse proxy, Docker, multi-instance setup
• Client configuration for HTTP transport (.mcp.json, Claude Code)

2. New: Authentication guide (docs/config/auth-token.mdx)

Why: --auth-token / DBHUB_AUTH_TOKEN support was added in #390, but the docs only mentioned it in passing. Auth is a security-sensitive topic — users deserve a complete, verified reference rather than inference from code.

What it covers:

• How bearer token auth works (opt-in via token presence, no separate flag)
• Setting the token: CLI flag, env var, .env file, Docker
• Client configuration: curl, .mcp.json, Claude Code
• Multiple tokens: comma-separated list for zero-downtime rotation and per-client tokens with independent revocation
• Security notes: constant-time comparison, flat shared-secret model (not OAuth), defense in depth
• Verification steps to confirm auth is actually enforced

Also simplified http-server.mdx to link to the new page instead of duplicating auth content.

3. New: SSH tunnel guide (docs/config/ssh-tunnel.mdx)

Why: SSH tunneling is a core deployment pattern for reaching databases on private networks, and DBHub has rich support for it (password, key, ProxyJump, ~/.ssh/config aliases). None of this was documented anywhere.

What it covers:

• Quick start with --ssh-host / --ssh-user / --ssh-key
• All four auth methods: password, SSH key (incl. passphrase), ProxyJump multi-hop, SSH config alias resolution
• TOML [[sources]] equivalents
• Troubleshooting common connection failures

4. New: REST API reference (docs/config/api-reference.mdx)

Why: The HTTP server exposes /api/sources and /api/requests (used by the Workbench frontend and useful for external tooling), but they were undocumented outside the code. External integrations had no reference for response shapes.

What it covers:

• GET /api/sources — configured sources (passwords/keys excluded from responses)
• GET /api/requests — tool execution traces (filterable by source_id)
• GET /healthz — unauthenticated health probe for uptime monitors
• Auth requirements per endpoint

5. Systematic fixes across existing pages (15 files)

• Frontmatter: added description to 12/19 pages that had only title (all tools, config, getting-started pages). Mintlify surfaces descriptions in search results and link previews; pages without them looked incomplete in search.
• execute-sql.mdx: added a Features table and a Parameters table; fixed factual errors:
  • Removed fabricated source_id / transaction / max_rows parameters — the actual tool schema has a single sql parameter (multi-source routing is by tool name suffix execute_sql_{source_id}, not by parameter)
  • Replaced the deprecated --max-rows CLI flag reference with the current TOML [[tools]] max_rows configuration (the flag now exits with an error pointing to TOML)
• See Also links: added missing cross-links to explain-sql, health-check, debug pages
• command-line.mdx: expanded the --id flag with a multi-instance scenario (e.g. running separate DBHub processes for different databases in Cursor/Claude Code)
• toml.mdx: expanded hot-reload behavior (what triggers it, stdio limitation, troubleshooting); removed a duplicated hot-reload section
• Nav (docs.json): registered all four new pages under Configuration

Verification

• All internal links resolve (checked against the full docs tree; no orphans)
• All flags referenced in the new pages exist in src/config/env.ts (verified each --ssh-*, --auth-token, --id, --transport, --demo, etc.)
• All API endpoints and response fields verified against src/server.ts
• Tool schemas verified against src/tools/*.ts (execute_sql, search_objects, explain_sql, health_check)
• Multi-token rotation and constant-time comparison claims verified against src/config/env.ts
• git diff origin/main is docs-only: 17 files, 811 insertions, 27 deletions

Notes

• Pure documentation changes — no behavior change, no test impact
• Commits are split by topic (http-server, auth-token, systematic fixes, parameter-table fix) to keep review easy
• Happy to adjust tone, structure, or split the PR further if you'd prefer smaller chunks

[tianzhou]

thanks for creating the PR. But we are not accepting large doc PR. Keeping the doc minimum and not spreading across different places is deliberate.

e.g. --auth-token is already mentioned https://dbhub.ai/config/command-line#%E2%80%94auth-token

[laserduor]

Thanks for the feedback — understood, and agreed that docs should stay minimal. I have split the changes into three small, focused PRs (each one single-purpose, no new standalone pages):

1. docs: replace deprecated --max-rows flag reference in execute_sql docs #396 — fix: replace deprecated --max-rows flag reference in execute_sql docs (the flag was removed from the CLI; the docs still described it) — 1 file, 1 line
2. docs: add See Also cross-links to tool and config pages #397 — docs: add See Also cross-links to explain_sql, health_check, and debug pages (all link targets verified to exist) — 3 files
3. docs: add description frontmatter to 12 pages #398 — docs: add description frontmatter to 12 pages (Mintlify search/preview metadata only) — 12 files, 1 line each

I dropped the standalone pages (HTTP server, auth-token, SSH tunnel, API reference) per your note that keeping docs minimal is deliberate. Happy to adjust any of the three further.