Epic: Remote mode hardening (thin CLI + shared server)

[bwl]

Status Update

This has moved from greenfield feature request to hardening/operations epic.

Forest now already has the core thin-client/server shape:

• forest serve backend
• local vs remote backend dispatch in CLI
• remote auth/config (serverUrl + apiKey)
• remote routes for key workflows

Remaining Gaps (What this issue now tracks)

• Deployment and rollback ergonomics for server operators
• API compatibility/versioning guarantees for remote clients
• Auth hardening (key scope/rotation and clearer failure modes)
• Operational docs: backups, restore, migrations, and upgrade playbooks
• Multi-client reliability testing (CLI + bot + web consumers)

Non-Goals for this issue

• Rebuilding the architecture from scratch (already done in principle)
• Product-layer features (dashboard UI, proactive surfacing, etc.)

Context

• Original intent remains valid: one canonical remote knowledge base + thin clients.

[bwl]

Cloud-native architecture landed (all 5 phases)

Commits f4e236c..484f59a implement the full plan from this issue:

Phase 1: Bearer token auth

FOREST_API_KEY env var enables auth on the server. Public paths (/, /api/v1/health, /swagger/*) are exempt. Returns 401 JSON error on bad/missing token. Backward compatible — auth disabled when env var is unset.

Phase 2: Config fields

serverUrl and apiKey added to ForestConfig with isRemoteMode() helper. Config wizard has interactive sections for both (URL validation, password input, update/clear/back). apiKey redacted in --show.

Phase 3: ForestClient

Pure-fetch ForestClient class in src/lib/client.ts — no deps. Typed methods for all API endpoints, ForestClientError class, auth header injection. Reusable by Telegram bot, desktop app, scripts.

Phase 4: Remote dispatch

8 commands gain remote mode: capture, read, search, edges, tags list, stats, delete, admin health. Pattern: check isRemoteMode() at top, call client, format output, return early. Local path unchanged.

Phase 5: Deployment

deploy/ directory with systemd service, Caddyfile (auto-TLS for forest.ettio.com), and setup README.

What's next

• Deploy to droplet and verify end-to-end
• Commands staying local-only for now: explore, edit, update, link, import, synthesize, write, lint, config, export
• Future: /api/v1/resolve?ref=@ endpoint for recency/tag refs over remote