langflower 0.0.4 → 0.0.5

package/README.md

@@ -32,7 +32,7 @@ proposed changes, and maintain a project wiki or Obsidian vault.
 
 Langflower also supports research fan-out and synthesis, reusable skills,
 prompt refinement, regression gates, and multi-agent review. Browse the
-[workflow scenarios](docs/use-cases/README.md).
+[workflow ideas](docs/public/workflows.md).
 
 ## How it works
 
@@ -75,10 +75,8 @@ The server owns the active session, while the browser is a view of it. Closing
 or reopening a tab does not create a competing workflow state or cancel a
 long-running job; the UI reconnects to the current progress.
 
-For builders: the runtime uses reactive ports, a strongly typed WebSocket
-contract, server-owned sessions, and UI projections of authoritative snapshots
-and runtime events. See [Architecture](docs/ARCHITECTURE.md) and
-[Execution architecture](docs/EXECUTION_ARCHITECTURE.md).
+For a short builder-oriented picture, see
+[How it works](docs/public/how-it-works.md).
 
 ## How it compares
 
@@ -113,19 +111,24 @@ Langflower opens a local UI at `http://127.0.0.1:4010` (or `--port` / the port
 in `.langflower/config.json`) for the selected folder. Use `-p` to run several
 instances from different folders at once.
 
-Maintainers: [docs/RELEASE.md](docs/RELEASE.md). CLI workspace:
+Full walkthrough: [Getting started](docs/public/getting-started.md).
+
+Maintainers (monorepo only): [docs/RELEASE.md](docs/RELEASE.md),
 [packages/cli/README.md](packages/cli/README.md).
 
 ## Learn more
 
-| Want to…                      | Start here                                                  |
-| ----------------------------- | ----------------------------------------------------------- |
-| Browse workflows and examples | [Use cases](docs/use-cases/README.md)                       |
-| Understand the product        | [Product](docs/PRODUCT.md)                                  |
-| Publish to npm                | [Release](docs/RELEASE.md)                                  |
-| Create custom nodes           | [Write reactive nodes](docs/HOW_TO_WRITE_REACTIVE_NODES.md) |
-| Understand the runtime        | [Architecture](docs/ARCHITECTURE.md)                        |
-| Follow the engineering model  | [Principles](docs/PRINCIPLES.md)                            |
+Shipped with the npm package under [`docs/public/`](docs/public/README.md):
+
+| Want to…                     | Start here                                          |
+| ---------------------------- | --------------------------------------------------- |
+| Install and first run        | [Getting started](docs/public/getting-started.md)   |
+| Understand the product       | [Product overview](docs/public/product.md)          |
+| Use the canvas and runs      | [Using the editor](docs/public/using-the-editor.md) |
+| Browse workflow ideas        | [Workflow ideas](docs/public/workflows.md)          |
+| Configure providers and keys | [Configuration](docs/public/configuration.md)       |
+| Add skills or custom nodes   | [Extending](docs/public/extending.md)               |
+| Builder runtime picture      | [How it works](docs/public/how-it-works.md)         |
 
 ## What Langflower is not
 

package/docs/public/README.md

@@ -0,0 +1,15 @@
+# Langflower manuals
+
+Short **user manuals** for people who install Langflower from npm. Deeper
+engineering docs live in the monorepo under [`docs/`](../) (not shipped in the
+package).
+
+| Manual                                     | Topic                                     |
+| ------------------------------------------ | ----------------------------------------- |
+| [Getting started](getting-started.md)      | Install, first run, ports                 |
+| [Product overview](product.md)             | What Langflower is (and is not)           |
+| [Using the editor](using-the-editor.md)    | Canvas, runs, human review, reconnect     |
+| [Workflow ideas](workflows.md)             | Common scenarios you can build            |
+| [Configuration](configuration.md)          | Providers, models, keys, project settings |
+| [Extending Langflower](extending.md)       | Skills and custom nodes                   |
+| [How it works (builders)](how-it-works.md) | Short runtime picture for extenders       |

package/docs/public/configuration.md

@@ -0,0 +1,56 @@
+# Configuration
+
+## Where settings live
+
+| Scope     | Typical path                                                    |
+| --------- | --------------------------------------------------------------- |
+| Project   | `<project>/.langflower/langflower.jsonc`                        |
+| Global    | OS app-data `langflower.jsonc` (Settings → Global)              |
+| Port / UI | `.langflower/config.json` (CLI `--port` overrides for that run) |
+
+Project settings override global for the same keys. Prefer the **Settings**
+gear in the UI for providers and models; hand-editing JSONC remains valid.
+
+Schemas are copied into `.langflower/schemas/` on bootstrap so editors that
+honour `$schema` get autocomplete.
+
+## Providers and models
+
+Add an OpenAI-compatible provider (OpenAI, LM Studio, or similar `baseURL`).
+Cursor does not expose an official OpenAI-compatible chat API for this path.
+
+API keys should stay in the environment. Reference them from config:
+
+```jsonc
+{
+	"provider": {
+		"openai": {
+			"options": {
+				"apiKey": "{env:OPENAI_API_KEY}",
+			},
+		},
+	},
+}
+```
+
+## Permissions
+
+Project `permission` entries set a **floor** for harness tools (read, write,
+bash, and so on). Agents and the Inspector can only tighten from there
+(ask / deny), not widen a project-level deny.
+
+Use this to keep explore-only runs from writing until you open that stage in
+the workflow.
+
+## Custom nodes and skills
+
+- Skills: markdown under `.langflower/skills/<name>/`
+- Custom nodes: packs under `.langflower/nodes/<pack>/`
+
+See [Extending Langflower](extending.md).
+
+## Logs
+
+Optional `serverLogs` in project or global config controls bridge diagnostics
+under `.langflower/logs/`. Use Settings radios (Off / On / Default) unless you
+prefer editing JSONC by hand.

package/docs/public/extending.md

@@ -0,0 +1,58 @@
+# Extending Langflower
+
+## Skills
+
+Skills are markdown playbooks the agent can load. Add a folder:
+
+```text
+.langflower/skills/my-skill/
+  SKILL.md
+```
+
+First-run bootstrap already seeds helper skills (for example
+`langflower-helper`). Keep skill text concrete: what the agent can and cannot
+do in your project.
+
+## Custom nodes
+
+Built-in catalog nodes and your packs share the same authoring SDK. Default
+path for a simple node:
+
+```ts
+import { defineNode } from '@langflower/node-sdk';
+
+export const myNode = defineNode({
+	type: 'my-pack/example',
+	displayName: 'Example',
+	category: 'Custom',
+	uiSchema: [] as const,
+	inputs: {
+		text: { wireType: 'string', required: true },
+	},
+	outputs: {
+		text: { wireType: 'string' },
+	},
+	run: async ({ inputs }) => ({
+		text: inputs.text,
+	}),
+});
+```
+
+Pack layout lives under `.langflower/nodes/<pack>/` (see the seeded
+`my-nodes` pack). Run `npm install` inside a pack when you add dependencies —
+Langflower does not auto-install pack deps.
+
+Use `defineReactiveNode` only when you need streaming / RxJS ports. Prefer
+`defineNode` for sync or Promise work.
+
+## After you change a pack
+
+Restart Langflower (or follow the product’s pack reload path when available)
+so the runtime picks up new node types. New nodes should appear in the node
+library for that project.
+
+## Deeper guides (monorepo)
+
+Full SDK and packaging details live in the Langflower repository (not in this
+npm package), under `docs/HOW_TO_WRITE_REACTIVE_NODES.md` and
+`docs/NODES.md`.

package/docs/public/getting-started.md

@@ -0,0 +1,61 @@
+# Getting started
+
+## Requirements
+
+- **Node.js ≥ 22**
+- A project folder on your machine (code, docs, or any workspace you want
+  Langflower to work in)
+
+## Install and run
+
+```bash
+npm install -g langflower
+langflower
+# or point at a folder:
+langflower ./my-project
+```
+
+Langflower starts a local server and opens the UI in your browser (default
+`http://127.0.0.1:4010`).
+
+Stop the process with Ctrl+C when you are done. There is no cloud account and
+no background daemon.
+
+### Several projects at once
+
+Use a different port for each instance:
+
+```bash
+langflower ./project-a -p 4010
+langflower ./project-b -p 4011
+```
+
+You can also set a port in `.langflower/config.json`; a CLI `-p` / `--port`
+overrides that for the current run only.
+
+## First run in a folder
+
+If the folder has no `.langflower/` directory yet, Langflower creates one with:
+
+- Default config and schemas
+- Starter workflows (default open: **starter**)
+- Helper skills and a seed custom-node pack under `.langflower/nodes/my-nodes/`
+
+Your own project files are left alone. Later starts reuse the existing
+`.langflower/` data.
+
+## Add an LLM provider
+
+Simple nodes and the Fake LLM work without a provider. Live agent runs need an
+OpenAI-compatible provider (OpenAI, LM Studio, or similar).
+
+1. Open **Settings** (gear) in the UI.
+2. Add a provider and model.
+3. Keep API keys in environment variables and reference them from config as
+   `{env:VAR_NAME}` — see [Configuration](configuration.md).
+
+## Next steps
+
+- [Using the editor](using-the-editor.md) — run a workflow and answer reviews
+- [Workflow ideas](workflows.md) — what to build next
+- [Configuration](configuration.md) — providers and permissions

package/docs/public/how-it-works.md

@@ -0,0 +1,39 @@
+# How it works (builders)
+
+A short picture for people extending Langflower. This is not a full
+architecture spec.
+
+## Pieces you interact with
+
+1. **CLI** — starts a local server for one project folder and opens the UI.
+2. **Server** — owns the session, workflows on disk, and the live run.
+3. **Runtime** — executes the graph: nodes exchange data on typed ports.
+4. **UI** — canvas + feed are views of server-owned state over a WebSocket
+   contract. Reconnecting the browser does not invent a second run.
+
+## Why review “just works”
+
+Steps are a live exchange of data. A node can wait for human input on a port
+and continue when you reply. That is ordinary graph behaviour, not a bolted-on
+interrupt mode.
+
+## Hard harness
+
+Edges and logic nodes define order. If QA or approval is on the graph, the
+model cannot skip it by claiming it is finished.
+
+## Extensibility surface
+
+| You add…     | Where                          |
+| ------------ | ------------------------------ |
+| Skills       | `.langflower/skills/`          |
+| Custom nodes | `.langflower/nodes/<pack>/`    |
+| Workflows    | `.langflower/workflows/`       |
+| Providers    | `.langflower/langflower.jsonc` |
+
+See [Extending](extending.md) and [Configuration](configuration.md).
+
+## Monorepo deep dives
+
+In the Langflower source tree (not shipped here): `docs/ARCHITECTURE.md`,
+`docs/EXECUTION_ARCHITECTURE.md`, and `docs/PRINCIPLES.md`.

package/docs/public/product.md

@@ -0,0 +1,43 @@
+# Product overview
+
+Langflower turns a **local folder** into a **repeatable AI workflow**.
+
+You point it at a workspace, open or create a visual workflow on a canvas, and
+let agents read, create, review, and update files there. You see every stage
+and decide what must happen before the next stage begins.
+
+**The workflow decides the process — not a model deciding it is “done.”**
+
+## Who it is for
+
+- **Near term:** developers running Langflower against an existing code repo
+- **Also useful for:** writing and refining files, research-style fan-out, and
+  maintaining project documentation in the same folder
+
+## What makes it different
+
+| Chat-style agent harnesses                           | Cloud / ETL graph tools                              |
+| ---------------------------------------------------- | ---------------------------------------------------- |
+| Pipeline order is fixed on the canvas (hard harness) | Aimed at **local daily work**, not hosting a service |
+| Review and QA stages cannot be skipped by the model  | Bootstrap into a real project folder quickly         |
+| You stay on your files, not only in chat history     | Same idea: reusable process, local folder centre     |
+
+### Hard harness
+
+1. The **graph** is the law — stages and edges are authored, not chosen by the
+   model at runtime.
+2. Logic nodes (gates, asserts, branches) can fail closed between agents when
+   you need a check.
+
+## What Langflower is not
+
+- Not a hosted multi-tenant cloud product
+- Not a generic cloud ETL clone
+- Not a replacement for your editor — it works **with** the files in your
+  project folder
+
+## Learn more
+
+- [Getting started](getting-started.md)
+- [Workflow ideas](workflows.md)
+- [How it works (builders)](how-it-works.md)

package/docs/public/using-the-editor.md

@@ -0,0 +1,53 @@
+# Using the editor
+
+## Open a project
+
+Start Langflower with your folder (see [Getting started](getting-started.md)).
+The toolbar shows which project directory is active. Switching projects means
+restarting the CLI with a different path.
+
+## Canvas and workflows
+
+- Pick a workflow from the project’s list, or create one.
+- Nodes are steps (agents, tools, review, logic). Edges define order and data
+  flow.
+- Open a node to edit its settings in the inspector.
+
+Built-in nodes appear in the node library. You can also add custom packs under
+`.langflower/nodes/` — see [Extending](extending.md).
+
+## Run a workflow
+
+1. Start a run from the editor.
+2. Watch progress on the canvas and in the feed (timeline of steps, messages,
+   and file activity).
+3. When a step asks for a human decision, answer in the feed / composer
+   (approve, reject, or send feedback).
+4. When the run finishes, find outputs in the same project folder.
+
+You can stop or pause a run from the UI when you need to redirect the work.
+
+## Human review
+
+Review is a normal part of the graph, not a special “interrupt mode.” If a
+workflow includes approval, fact check, or rewrite stages, the run waits for
+you and continues when you reply.
+
+Sensitive file edits or shell commands can also ask permission before they
+run — configure the floor in project settings
+([Configuration](configuration.md)).
+
+## Close the browser and come back
+
+The **server** owns the active session. Closing the browser tab does not cancel
+a long-running job. Reopen the same UI URL while the CLI process is still
+running; the editor reconnects to current progress.
+
+When you stop the CLI process (Ctrl+C), that session ends.
+
+## Tips
+
+- Keep one Langflower process per project (or use different ports).
+- Prefer small, reusable workflows you can apply to similar folders.
+- Put durable instructions in skills under `.langflower/skills/` rather than
+  only in chat — see [Extending](extending.md).

package/docs/public/workflows.md

@@ -0,0 +1,49 @@
+# Workflow ideas
+
+Examples of processes people build on the canvas. Status of each scenario in
+the monorepo may still be Partial — treat this list as a **menu of shapes**,
+not a guarantee that every Expect is production-ready.
+
+## Coding change
+
+Clarify the request → implement → review → QA → accept. Use human gates where
+you need a plan check or final approval. The graph keeps review and QA in the
+pipeline so the model cannot skip them.
+
+## Write and refine a file
+
+Topic or brief → draft file in the workspace → tone / fact review → revise in
+place. The useful result is a file you own, not only a chat transcript.
+
+## Prompt or skill refinement
+
+Draft a prompt or skill markdown file, run it against fixtures or a short
+eval loop, improve it, and keep the improved file in the project.
+
+## Research fan-out
+
+Map several research branches, collect results, then synthesize (and optionally
+review conflicts) before writing a summary into the folder.
+
+## Permission-staged ops
+
+Explore with read-only tools first, then allow writes, then shell — each stage
+tightened with permission asks so destructive steps stay explicit.
+
+## Checkpoints and long runs
+
+For longer jobs, place explicit checkpoint boundaries and resume from the
+picker when you return. Closing the browser mid-run is fine while the Langflower
+process stays up — see [Using the editor](using-the-editor.md).
+
+## Multi-agent review
+
+Wire more than one model or Sub-Agent path for adversarial or swarm-style
+review, then merge through a review gate before accepting a result.
+
+## Getting started templates
+
+A new project seeds starter workflows under `.langflower/workflows/`. Open
+**starter** first, then copy or adapt graphs for your task. Refresh packaged
+templates from Settings → Bootstrap when you want newer seeds (it does not
+rewrite your main `langflower.jsonc`).

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "langflower",
-	"version": "0.0.4",
+	"version": "0.0.5",
 	"description": "Visual LLM-chain builder",
 	"type": "module",
 	"bin": {
@@ -11,7 +11,8 @@
 		"dist",
 		"bin",
 		"ui-dist",
-		"vendor"
+		"vendor",
+		"docs/public"
 	],
 	"engines": {
 		"node": ">=22.22.3"