@synap-core/cli 1.1.0 → 1.2.1

package/README.md

@@ -6,19 +6,12 @@ Connect [OpenClaw](https://github.com/openclaw/openclaw) to your Synap pod — s
 npx @synap-core/cli init
 ```
 
----
-
-## What it does
-
-`synap init` walks you through three paths depending on your setup:
-
-| Path | When to use |
-|------|-------------|
-| **A** — Existing OpenClaw | OpenClaw is already running, just connect it to Synap |
-| **B** — Fresh install | No OpenClaw yet — generates config, you run `openclaw --config synap.json` |
-| **C** — Managed pod | Point to your Synap cloud pod, CLI handles everything |
-
-After init, your AI agent gets structured memory (entities, relationships, full-text search, knowledge graph) via the `synap` OpenClaw skill.
+After `synap init` + `synap finish`, you get:
+- A running Synap pod with the `synap` skill installed in OpenClaw
+- OpenClaw connected to Synap's structured memory, entities, documents, and governance layer
+- An AI provider key configured inside OpenClaw
+- A public HTTPS dashboard URL (managed pods) — no SSH tunnel needed
+- MCP client configs (Claude Desktop / Cursor / Windsurf) ready to paste
 
 ---
 
@@ -35,161 +28,215 @@ synap init
 
 **Requirements**: Node.js 20+
 
-> Detailed setup for Linux servers, Docker, SSH environments, and permission issues: [docs/INSTALL.md](docs/INSTALL.md)
+Detailed environment setup: [docs/INSTALL.md](docs/INSTALL.md)
 
 ---
 
-## Commands
+## The two-command flow
 
-### `synap init`
+`synap init` + `synap finish` is the full path. `init` handles detection and provisioning; `finish` wires everything up.
 
-Full setup wizard. Detects OpenClaw, connects to a pod, installs the skill, seeds the Agent OS workspace.
+### `synap init`
 
-```bash
-synap init
-```
+Detects your environment and picks one of three paths:
 
-If OpenClaw is being provisioned on a managed server, setup may take a few minutes. Run `synap finish` once it's ready.
+| Path | When |
+|---|---|
+| **A** — Existing OpenClaw | OpenClaw is already running locally |
+| **B** — Fresh server | No OpenClaw — starts pod + OpenClaw via Docker |
+| **C** — Desktop / managed pod | Connects to a Synap-hosted pod |
 
----
+On a fresh server, OpenClaw's first boot takes a few minutes (image pull + init). Run `synap finish` once it's up.
 
 ### `synap finish`
 
-Complete the setup after OpenClaw has started (managed pod path). Installs the skill, seeds entities, configures the intelligence service.
+One-shot completion. Runs:
+1. **Skill install** — `openclaw skills install synap` (from ClawHub)
+2. **Workspace seed** — creates Agent OS entities
+3. **AI provider setup** — prompts you for a key if OpenClaw doesn't have one, writes it via `openclaw config set env.ANTHROPIC_API_KEY …`
+4. **Public dashboard** (managed pods) — offers to expose `openclaw.yourpod.synap.live` via the CP, with Synap-session-based auth (no extra password)
+5. **Intelligence Service** — optional, routes AI through your pod
+
+After this, everything is ready. No follow-up commands.
 
+Flags:
 ```bash
-synap finish
+synap finish --skip-ai-key    # Don't prompt for AI key
+synap finish --skip-domain    # Don't offer public domain
+synap finish --skip-is        # Don't configure IS
 ```
 
-Run this after `synap init` if prompted — it's the second half of the managed pod flow.
-
 ---
 
-### `synap status`
+## `synap openclaw` — everything OpenClaw
 
-Show the health of your entire stack at a glance.
+Wraps the things you actually need after install.
 
-```bash
-synap status
-```
+### `synap openclaw`
 
-Output covers:
-- **Account** — login state, token expiry
-- **OpenClaw** — local running state, or remote provisioning state on your pod
-- **Synap Pod** — URL, health, version
-- **Workspace Config** — workspace ID, agent user, when config was saved
-- **Intelligence Service** — whether AI is provisioned
-- **Synap Skill** — whether the skill is installed in OpenClaw
-- **Next Steps** — what to do next
+Overview: gateway status, AI provider, skill, dashboard URL, next steps.
 
----
+### `synap openclaw dashboard`
 
-### `synap login`
+Opens the OpenClaw web UI. If a public domain is configured, opens it directly. Otherwise opens `http://localhost:18789` or — on a remote Linux server — prints an SSH tunnel command.
 
-Sign in to your Synap account. Required for managed pod flows.
+### `synap openclaw connect`
+
+Generates MCP client configs for Claude Desktop, Cursor, Windsurf — **with the gateway token pre-filled** so remote setups work without manual editing.
 
 ```bash
-synap login                      # Opens browser
-synap login --token <token>      # Headless / server environments
+synap openclaw connect                  # All three clients
+synap openclaw connect --client claude  # Just Claude Desktop
 ```
 
-For servers without a browser, generate a token at [synap.live/account/tokens](https://synap.live/account/tokens) and use `--token`.
+### `synap openclaw configure`
 
-Your session is kept alive automatically — as long as `synap status` or `synap init` succeeds at least once every 7 days, you won't need to re-login.
+Sets OpenClaw's AI provider via its own config system (`openclaw config set env.ANTHROPIC_API_KEY …`). No `.env` hacking — the real OpenClaw config layer.
 
----
+```bash
+# Interactive (in CLI)
+synap openclaw configure
 
-### `synap logout`
+# Interactive (hand off to OpenClaw's own wizard)
+synap openclaw configure --interactive
+
+# Scripted
+synap openclaw configure --provider anthropic --key sk-ant-... --model anthropic/claude-sonnet-4-6
 
-Remove stored credentials.
+# Read current config
+synap openclaw configure --show
+```
+
+### `synap openclaw token`
+
+Reads the OpenClaw gateway token from the container. You need this to connect MCP clients to a remote gateway.
 
 ```bash
-synap logout
+synap openclaw token                  # Print it
+synap openclaw token --copy           # Copy to clipboard
+synap openclaw token --for claude     # Print a ready-to-paste Claude Desktop config
 ```
 
----
+### `synap openclaw setup-domain`
 
-### `synap connect`
+Expose the OpenClaw dashboard at a public HTTPS URL.
+
+- **Managed pods** (`*.synap.live`): calls the CP to create a DNS A record automatically (`openclaw.yourpod.synap.live`), wires Caddy's `forward_auth` to validate your existing Synap session cookie. Zero manual auth.
+- **Self-hosted**: prompts for a subdomain, tells you which DNS A record to add, generates a random 32-char password, and writes a Caddy basic-auth gate. Hashes via `caddy hash-password` — no bcrypt dependency.
+
+Both modes forge `X-Real-IP: 127.0.0.1` at the Caddy layer so OpenClaw treats requests as loopback and skips device pairing. Auth is enforced at the Caddy layer.
+
+### `synap openclaw doctor`
 
-Connect to a pod that was already provisioned (skip the full init wizard).
+Thin wrapper around OpenClaw's own diagnostic. Use `--fix` to auto-repair known issues.
 
 ```bash
-synap connect
+synap openclaw doctor
+synap openclaw doctor --fix
 ```
 
+### `synap openclaw logs`
+
+```bash
+synap openclaw logs              # Last 50 lines
+synap openclaw logs -n 200       # More
+synap openclaw logs -f           # Follow
+```
+
+### `synap openclaw restart`
+
+Restart the container. Handy after config changes.
+
 ---
 
-### `synap security-audit`
+## Top-level commands
+
+### `synap status`
+
+Health check across the stack: pod, OpenClaw, auth, skill, Intelligence Service.
 
-Check your OpenClaw + Synap config for common security issues (API key exposure, outdated versions, HTTPS enforcement, etc.).
+### `synap login`
 
 ```bash
-synap security-audit
-synap security-audit --fix    # Auto-fix what's fixable
+synap login                      # Opens browser
+synap login --token <token>      # Headless / server
 ```
 
-Example output:
+Token: [synap.live/account/tokens](https://synap.live/account/tokens). Your session auto-refreshes for 7 days.
 
-```
-  ✓ Gateway bound to loopback
-  ✓ Token authentication enabled
-  ✗ OpenClaw version 2026.2.x — CRITICAL (9.9 CVSS)
-  ✓ No plaintext credentials
-  ✗ ~/.openclaw world-readable
-  ✓ WebSocket origin validation
-  ✓ Dangerous skill scanner
-  ✓ Workspace filesystem access
-  ✓ Exec approval gates
-
-  Score: B  (2 issues, 1 critical)
-```
+### `synap logout`
 
----
+### `synap connect`
+
+Re-connect to an existing pod without running the full init wizard.
 
 ### `synap update`
 
-Update the Synap skill in your OpenClaw installation to the latest version.
+Update the synap skill in OpenClaw to the latest version.
+
+### `synap security-audit`
+
+Check OpenClaw + Synap config for known security issues. `--fix` auto-repairs fixable ones.
+
+---
+
+## Why split `synap openclaw configure` from `openclaw configure`?
 
+We delegate to OpenClaw's own config system for the actual write (`openclaw config set env.ANTHROPIC_API_KEY …`) but wrap it for:
+
+1. **Docker exec** — handles the `docker exec openclaw …` for you
+2. **Restart** — auto-restarts the container (Docker mode has no hot-reload)
+3. **Scripted mode** — `--provider` / `--key` flags for automation
+4. **Integration with `synap finish`** — part of the one-shot flow
+
+For anything we don't wrap, use OpenClaw directly:
 ```bash
-synap update
+docker exec -it openclaw openclaw configure   # Interactive wizard
+docker exec openclaw openclaw config get <key>
+docker exec openclaw openclaw skills list
+docker exec openclaw openclaw channels add --channel telegram --token ...
 ```
 
+`synap` owns: Synap pod connection, skill install, Caddy proxy auth, CP DNS provisioning.
+`openclaw` owns: models, skills, channels, daemon, gateway config.
+
 ---
 
-## Configuration
+## Configuration files
 
-The CLI stores config in `~/.synap/` (user-only, `chmod 600`):
+Stored in `~/.synap/` (user-only, `chmod 600`):
 
 | File | Contents |
-|------|----------|
+|---|---|
 | `credentials.json` | CP auth token |
 | `pod-config.json` | Pod URL, workspace ID, agent user ID, Hub API key |
 
-Never commit these files.
+Never commit these.
 
 ### Environment variables
 
 | Variable | Default | Description |
-|----------|---------|-------------|
-| `SYNAP_CP_URL` | `https://api.synap.live` | Control plane API URL |
-| `SYNAP_LANDING_URL` | `https://synap.live` | Landing page URL (for OAuth callback) |
+|---|---|---|
+| `SYNAP_CP_URL` | `https://api.synap.live` | Control plane URL |
+| `SYNAP_LANDING_URL` | `https://synap.live` | Landing page (OAuth callback) |
 
 ---
 
-## How the skill works
+## What the `synap` skill gives your agent
 
-The `synap` OpenClaw skill gives your AI agents access to Synap's Hub Protocol:
+The skill is published on [ClawHub](https://clawhub.ai) as `synap`. Once installed, your agent gains access to Synap's Hub Protocol:
 
-| What | How the agent uses it |
-|------|----------------------|
-| Store a memory | Save a fact — keyword or semantic search |
-| Search memories | Find relevant facts across everything stored |
+| Capability | How the agent uses it |
+|---|---|
+| Store a memory | Save atomic facts, keyword or semantic search |
 | Create an entity | Structured object (person, task, note, project, …) |
-| Search entities | Find by name, type, or content |
-| Send a message | Post to any channel |
-| Create a proposal | Propose a change for human review |
+| Search entities | By name, type, content, relationships |
+| Relation graph | Link entities, traverse |
+| Documents | Long-form markdown with governance |
+| Channels | Post messages to any Synap channel |
+| Proposals | Request changes for human review |
 
-Agents self-discover available entity types and views at runtime — no hardcoding.
+Agents self-discover entity types and views at runtime — no hardcoding.
 
 ---
 
@@ -199,51 +246,47 @@ Agents self-discover available entity types and views at runtime — no hardcodi
 
 ```bash
 git clone https://github.com/synap-core/synap-backend
-cd synap-backend
+cd synap-backend/deploy
 docker compose --profile openclaw up -d
-# then:
-synap init  # → "Connect to existing pod"  → http://localhost:4000
+synap init  # → "Connect to existing pod" → http://localhost:4000
 ```
 
 ### Managed pod ($15–20/mo)
 
 1. Create a pod at [synap.live](https://synap.live)
-2. Run `synap init` → "Connect to my Synap cloud pod"
-3. Select your pod — CLI handles provisioning
+2. `synap init` → "Connect to Synap cloud pod"
+3. Select your pod — CLI handles everything
+4. `synap finish` — offers public domain automatically
 
 ---
 
 ## Troubleshooting
 
 **"Could not reach pod"**
-Check that your pod URL is reachable. For self-hosted, make sure Docker Compose is up and port 4000 is accessible.
+Pod unreachable. Check `synap status` and docker compose.
 
-**"No workspace found on this pod"**
-The CLI auto-creates an Agent OS workspace on first connect. Re-run `synap init` — it's idempotent.
+**"OpenClaw is not running yet"**
+First boot takes 1–2 minutes. Wait, then `synap finish`.
 
-**"OpenClaw provisioning error"** (managed pod, `serverIp null`)
-Your managed pod doesn't have a registered server IP (trial pods). Install OpenClaw locally instead:
-```bash
-npm i -g openclaw
-synap init  # → Path A
-```
+**"AI provider not configured"**
+Run `synap openclaw configure` — or use `synap openclaw configure --interactive` to hand off to OpenClaw's own wizard.
 
-**Login on a remote server (no browser)**
-```bash
-synap login --token <your-token>
-# Generate token at: https://synap.live/account/tokens
-```
+**MCP client doesn't show tools**
+Run `synap openclaw token --for claude` to get a ready-to-paste config with the token pre-filled. Restart your AI client.
+
+**Dashboard: "device approval required"**
+Shouldn't happen — `synap openclaw setup-domain` forges `X-Real-IP: 127.0.0.1` so OpenClaw treats Caddy traffic as loopback. If it does, run `synap openclaw doctor --fix`.
 
 **"Session expired" in synap status**
-Run `synap login` again. In normal use the session auto-refreshes and you should only need to login once.
+Run `synap login --token <token>` on the server.
 
 ---
 
 ## Why Synap
 
-- **Structured memory**: OpenClaw's `MEMORY.md` is flat files. Synap gives you PostgreSQL + pgvector + Typesense — entities, relationships, full-text + semantic search.
-- **Governance**: AI agent mutations go through proposals — reviewable, reversible, auditable.
-- **Sovereign**: Self-host for free. Your data stays on your infrastructure.
+- **Structured memory**: not flat files. PostgreSQL + pgvector + Typesense. Entities, relationships, full-text + semantic search.
+- **Governance**: AI mutations go through reviewable proposals.
+- **Sovereign**: self-host for free, your data stays yours.
 
 ---
 

package/dist/commands/finish.d.ts

@@ -1,18 +1,25 @@
 /**
  * synap finish
  *
- * Complete setup after OpenClaw has been provisioned.
- * Run this once OpenClaw is running (a few minutes after synap init).
+ * Complete setup after OpenClaw has been provisioned. One-shot: after this
+ * command, everything the user needs is ready — AI key, skill, IS, and public
+ * dashboard URL.
  *
  * Steps:
- *  1. Verify pod connection (reads ~/.synap/pod-config.json)
+ *  1. Verify pod connection (~/.synap/pod-config.json)
  *  2. Check pod health
  *  3. Check OpenClaw is running
- *  4. Security audit
- *  5. Install synap skill
+ *  4. Security audit (local-install only)
+ *  5. Install synap skill (via openclaw skills install)
  *  6. Seed workspace entities
- *  7. Optionally configure IS as AI provider
+ *  7. Configure AI provider — prompt if missing (via openclaw config set)
+ *  8. Expose dashboard — offer if managed pod + OPENCLAW_DOMAIN unset
+ *  9. Configure Synap IS as AI provider (optional)
  */
-export declare function finish(opts?: {
+interface FinishOpts {
     skipIs?: boolean;
-}): Promise<void>;
+    skipAiKey?: boolean;
+    skipDomain?: boolean;
+}
+export declare function finish(opts?: FinishOpts): Promise<void>;
+export {};