@tuongaz/seeflow 0.1.18 → 0.1.22

package/README.md

@@ -20,8 +20,24 @@ The SeeFlow plugin reads your codebase, understands your architecture, and gener
 
 ```bash
 npx tuongaz/seeflow start
+# then open http://localhost:4321
+```
+
+Requires Bun ≥ 1.3 (or Node with npx). The studio scans `$(pwd)/.seeflow/seeflow.json` on start and auto-registers that flow if present. Flows you create from the UI, plus the studio's registry, persist under `$(pwd)/.seeflow/` across restarts.
+
+<details>
+<summary>Prefer Docker? (not recommended)</summary>
+
+> ⚠️ **Heads up:** Play and Status scripts run **inside** the container, so generated scripts that talk to services on your host — HTTP calls to `localhost`, host binaries like `psql` / `redis-cli`, your project's CLI — will not work. Interactive nodes are likely to fail. Use the native path above for full functionality.
+
+```bash
+docker run --rm -it -p 4321:4321 -v $(pwd):/workspace tuongaz/seeflow
 ```
 
+The image ships with a pre-registered **Order Pipeline** demo so you can see the canvas immediately, and the studio scans `/workspace/.seeflow/seeflow.json` on start.
+
+</details>
+
 ### 2. Install the plugin
 
 **Skill installer (recommended):**
@@ -51,24 +67,23 @@ curl -fsSL https://raw.githubusercontent.com/tuongaz/seeflow/main/install.sh | b
 
 The plugin scans your routes and database connections, generates `seeflow.json`, wires up demo scripts, and opens the canvas at localhost:4321.
 
-## Run with Docker
+## Docker reference
 
-Try SeeFlow without installing Bun or Node:
+> ⚠️ Docker is the non-preferred path. Play/Status scripts execute inside the container and cannot reach host services or host binaries, so interactive nodes generated against your local app will not work. Prefer `npx tuongaz/seeflow start` for the full experience.
 
-```bash
-docker run --rm -it -p 4321:4321 -v $(pwd):/workspace tuongaz/seeflow
-# then open http://localhost:4321
-```
+The image is published on [Docker Hub](https://hub.docker.com/r/tuongaz/seeflow). See Quick Start above for the basic `docker run`.
 
-The studio scans `/workspace/.seeflow/seeflow.json` on start and auto-registers that flow if present.
+### Configuration
 
-Runtime env vars:
+| Variable            | Default                 | Description                                |
+| ------------------- | ----------------------- | ------------------------------------------ |
+| `SEEFLOW_PORT`      | `4321`                  | Port the studio listens on                 |
+| `SEEFLOW_FLOW`      | `.seeflow/seeflow.json` | Flow file path relative to the workspace   |
+| `SEEFLOW_WORKSPACE` | `/workspace`            | Workspace mount point inside the container |
 
-- `SEEFLOW_PORT` — port the studio listens on (default `4321`)
-- `SEEFLOW_FLOW` — flow file path relative to the workspace (default `.seeflow/seeflow.json`)
-- `SEEFLOW_WORKSPACE` — workspace mount point inside the container (default `/workspace`)
+### Bake demos into a derived image
 
-Bake demos into a derived image so the container ships with your flow:
+Ship a container that already contains your flow:
 
 ```dockerfile
 FROM tuongaz/seeflow
@@ -76,7 +91,11 @@ COPY ./my-demos /workspace
 # docker build -t my-flow . && docker run --rm -it -p 4321:4321 my-flow
 ```
 
-Published image tags: `:latest`, `:<version>` (e.g. `:0.1.16`), and `:<major>.<minor>` (e.g. `:0.1`).
+### Tags
+
+- `:latest` — newest stable release
+- `:<version>` — pinned release (e.g. `:0.1.18`)
+- `:<major>.<minor>` — latest patch on a minor line (e.g. `:0.1`)
 
 ## MCP server