langflower 0.0.9 → 0.1.0

package/vendor/server/skeleton/skills/langflower-helper/SKILL.md

@@ -54,11 +54,15 @@ On-demand only (not auto-injected). Use harness `read`:
 
 ### 1. Product
 
-- **Can:** Local, project-scoped coding agent. The **workflow graph** is the
-  pipeline law (hard harness) — stages and edges are authored, not chosen
-  ad hoc by the model each turn.
+- **Can:** Local, folder-scoped **reactive node graph**. The LLM is a node,
+  not the product. The **workflow graph** is the pipeline law (hard harness)
+  — stages and edges are authored, not chosen ad hoc by the model each turn.
+  Extend with **MCP** and **skills**, plus **custom nodes** for graph
+  processing or custom tools via the same **ToolHandle** contract as built-ins.
 - **Cannot:** Require a cloud account. Let the model skip graph stages
-  (QA/review/gates) by “deciding what’s next” outside the graph.
+  (QA/review/gates) by “deciding what’s next” outside the graph. Claim
+  serializable **chat sessions**, **image/video** asset management for
+  multimodal models, or a built-in **IDE / git UI**.
 
 ### 2. Project layout and bootstrap
 
@@ -67,11 +71,13 @@ templates in the skeleton are **already usable** once copied into the project
 do not say coding pipelines “don’t exist” or are unavailable.
 
 - **Can:** `langflower start [project-dir]` (default port **4010**) creates
-  `.langflower/`, config, `instructions.md`, pack `nodes/my-nodes/`, skills
+  `.langflower/`, config, `instructions.md`, packs `nodes/my-nodes/` and
+  `nodes/hello-embed/`, skills
   `langflower-helper`, `langflower-node-writer`, and
   `langflower-workflow-writer`, and opens workflow **`starter`** first.
 - **Can:** Skeleton already ships coding and KB sample workflows
-  (`simple-coder`, `advanced-coder`, `kb-create`, `kb-navigate`, …). With a
+  (`simple-coder`, `advanced-coder`, `kb-create`, `kb-navigate`,
+  `kb-ingest`, `kb-manual-search`, `kb-tool`, `kb-rag`, …). With a
   provider configured, they are seeded on first-run → load → composer **Start**.
 - **Can:** Second `langflower start` on an existing `.langflower/` **reuses**
   it as-is (no wipe).
@@ -88,10 +94,12 @@ do not say coding pipelines “don’t exist” or are unavailable.
 ### 3. Skeleton and samples
 
 - **Can:** First-run seed = config + **all** skeleton workflows (including
-  `starter`, coding samples, `kb-create`, `kb-navigate`) + three skills +
-  `my-nodes` + instructions.
+  `starter`, coding samples, `kb-create`, `kb-navigate`, `kb-ingest`,
+  `kb-manual-search`, `kb-tool`, `kb-rag`) + three skills + `my-nodes` +
+  `hello-embed` + instructions.
 - **Can:** Skeleton inventory includes `node-writer`, `agents-dialog`,
-  `simple-coder`, `advanced-coder`, `kb-create`, `kb-navigate` (and other
+  `simple-coder`, `advanced-coder`, `kb-create`, `kb-navigate`,
+  `kb-ingest`, `kb-manual-search`, `kb-tool`, `kb-rag` (and other
   samples under `packages/server/skeleton/` / demo-project).
 - **Cannot:** Claim a Sample workflows **catalog UI** (browse / help /
   one-click copy) is shipped.
@@ -111,14 +119,49 @@ do not say coding pipelines “don’t exist” or are unavailable.
 - **Cannot:** Treat Settings as the selected-node inspector (ports/params).
 - **Cannot:** Reveal a saved API key in the UI.
 
+### 4b. Embeddings
+
+- **Can:** Settings **Default embedding model** (`embedding: "providerId/modelId"`);
+  palette **Embeddings** — `common-embed-text`, `common-embed-similarity`,
+  `common-embed-provider`; custom packs wire **`embed`** (`EmbedHandle` from
+  `@langflower/node-sdk`); server binds embedding HTTP — packs never see
+  `apiKey`. Manual check: String → Embed text → Preview on **`preview`**.
+  Sample pack **`hello-embed`**: ingest project `.md` → sqlite (vectors + FTS5);
+  hybrid retrieve (cosine + keyword, RRF) packs **Question + full-chunk Context**
+  for `hello-embed-search` / `project_search`.
+  Workflows `kb-ingest` / `kb-manual-search` / `kb-tool` / `kb-rag`. Needs
+  the default embedding model (`langflower start` compiles the pack). Copy
+  the pack for a different corpus — see `nodes/hello-embed/README.md`.
+- **Cannot:** Treat embeddings as a host catalog feature. Use **`EmbedHandle`**
+  (not `ToolHandle`) for batch float vectors. hello-embed sqlite lives under
+  `.langflower/.cache/hello-embed/`.
+
+### 4c. Primitives and paced split
+
+- **Can:** Palette **Primitives** include String, **String (multiline)**
+  (`common-string-multiline`, textarea), Number, Boolean. **Text** includes
+  Concat, Read/Write/Append File, and **Split (paced)** (`common-split-paced`)
+  — one non-empty chunk per `trigger` (first ASAP; `finish` after the last;
+  CSV / logs line-by-line). Not the planned one-shot Split (`parts[]`).
+
 ### 5. Editor chrome
 
 - **Can:** Chat Input graphs start from the composer **Start** control. Plain
-  **Run** stays disabled for those graphs.
+  **Run** stays disabled for those graphs. Prefill or last typed text lives on
+  the Chat Input node (`inputs.message`) and reappears after Stop.
 - **Can:** While running — Hard **Stop**, soft **Pause**, HITL and
-  `permission.ask` in the composer.
+  `permission.ask` in the composer. Work log **clears** on successful
+  workflow load / create / copy (not rename).
+- **Cannot:** Switch, rename, delete, copy, or create a workflow while a run
+  is active — Stop first. Same lock: inspector / canvas inline / palette
+  drag (`cursor-not-allowed`).
 - **Cannot:** Tell users to press plain **Run** to start a Chat Input graph.
 - **Cannot:** Claim the feed after reload must be **richer** than live.
+- **Can:** Work log shows opted-in roles (`reasoning` / `draft` / `result` /
+  tools / `progress`) plus Finish **`done`** and Preview content as result
+  bubbles. Unmarked ports and `feed.role: 'none'` are omitted.
+- **Cannot:** Claim unmarked plumbing (`prompt` / `value` wires) appears as
+  muted technical rows — use the inspector for those values.
 - **Cannot:** Claim `basic-coder` proves chat-dense mood for the full
   `coding-agent` pipeline.
 
@@ -130,18 +173,43 @@ do not say coding pipelines “don’t exist” or are unavailable.
   cleaned graph. Catalog list still shows the file (metadata-only).
 - **Cannot:** Silently rewrite disk on load. Invent port renames — only drop.
 
+### 5c. Multi input ports
+
+Extra empty handles on a node are **one logical port** authored with `multi`
+(`merge` / `combine` / `zip`). Wiring a slot **grows a trailing empty slot**
+on that same port so you can connect another source. Leave the empty row
+unwired — it is not a duplicate Helper, not a second node, and not a bug.
+
+- **Can (starter Helper `feedback`):** `multi: 'merge'` — several sources can
+  kick a new agent turn. Example: Review Gate HITL **and** `common-review`
+  auto-review.
+- **Can (starter Helper `tools`):** `multi: 'combine'` — several packs land on
+  one agent. Example: Langflower Tools **and** Writer Sub-Agent. Optional
+  **Tool collection** (`common-tool-collection`) can still merge wires first;
+  direct multi-wire still works.
+- **Can (Router):** `common-router` uses the same extra-slot growth for
+  channels (`ch` / `ch@1` / …) so many edges stay readable.
+- **Cannot:** Claim every port grows this way — `userPrompt` / `systemPrompt`
+  stay single. Claim the empty slot must be wired. Equate `merge` (each emit
+  is a turn) with `combine` (inventory array) with `zip` (lockstep, e.g.
+  Concat).
+
 ### 6. Coding workflows
 
-| Name           | Fact                                                                                                                                                                                                                                                                                               |
-| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `starter`      | Onboarding chat + this skill + Writer Sub-Agent (`langflower-workflow-writer` + `langflower-node-writer`) — default open after seed                                                                                                                                                                |
-| Skeleton stubs | `simple-coder`, `advanced-coder`, `kb-create`, `kb-navigate`, … seeded on first-run; with provider → Start                                                                                                                                                                                         |
-| `simple-coder` | Plan⇄HITL→Coder⇄HITL→Finish smoke spine + `common-memory-tools` on Plan/Coder/Researcher/Worker; Researcher Sub-Agent under Plan, Worker under Coder — **not** full multi-loop `coding-agent`                                                                                                      |
-| `kb-create`    | Memory / project wiki create: Orchestrator **indexes** the repo with `glob`/`read`, persists `history/work-queue.md`, then **serially** spawns Explorer → Composer **one unit at a time**; `common-memory-tools` writes `core/*` + `modules/*`; Review rejects non-empty Pending or thin overviews |
-| `kb-navigate`  | Memory navigate: Navigator + Searcher + memory tree/grep/section tools; HITL Review Gate for follow-ups                                                                                                                                                                                            |
-| `basic-coder`  | Basic coding harness (Plan⇄HITL→Coder⇄HITL→Finish) — not a toy, **not** full multi-loop `coding-agent`                                                                                                                                                                                             |
-| `coding-agent` | Clarify HITL → red team → plan gate → coder → QA → `common-review` → result HITL; **graph** orders stages                                                                                                                                                                                          |
-| Status         | Use-case **Partial**; real-LLM Implementable bar open; Fake CI ≠ end-user proof — **not** “no templates”                                                                                                                                                                                           |
+| Name               | Fact                                                                                                                                                                                                                                                                                              |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `starter`          | Onboarding chat + this skill + Writer Sub-Agent (`langflower-workflow-writer` + `langflower-node-writer`) — default open after seed                                                                                                                                                               |
+| Skeleton stubs     | `simple-coder`, `advanced-coder`, `kb-create`, `kb-navigate`, `kb-ingest`, `kb-manual-search`, `kb-tool`, `kb-rag`, … seeded on first-run; with provider → Start                                                                                                                                  |
+| `simple-coder`     | Plan⇄HITL→Coder⇄HITL→Finish smoke spine + `common-memory-tools` on Plan/Coder/Researcher/Worker; Researcher Sub-Agent under Plan, Worker under Coder — **not** full multi-loop `coding-agent`                                                                                                     |
+| `kb-create`        | Memory / project wiki create: Orchestrator **indexes** the repo with `glob`/`read`, persists `history/work-queue.md`, then **serially** calls Explorer → Composer **one unit at a time**; `common-memory-tools` writes `core/*` + `modules/*`; Review rejects non-empty Pending or thin overviews |
+| `kb-navigate`      | Memory navigate: Navigator + Searcher + memory tree/grep/section tools; HITL Review Gate for follow-ups                                                                                                                                                                                           |
+| `kb-ingest`        | Sample **hello-embed** ingest (Settings embedding model; pack compiles on `langflower start`)                                                                                                                                                                                                     |
+| `kb-manual-search` | Sample hello-embed query → Preview / Finish                                                                                                                                                                                                                                                       |
+| `kb-tool`          | Sample hello-embed `project_search` ToolHandle → agent                                                                                                                                                                                                                                            |
+| `kb-rag`           | Simplified RAG: hybrid retrieve packs Question + full chunks into the LLM; `project_search` + grep/read; Review feedback / Approve → Finish                                                                                                                                                       |
+| `basic-coder`      | Basic coding harness (Plan⇄HITL→Coder⇄HITL→Finish) — not a toy, **not** full multi-loop `coding-agent`                                                                                                                                                                                            |
+| `coding-agent`     | Clarify HITL → red team → plan gate → coder → QA → `common-review` → result HITL; **graph** orders stages                                                                                                                                                                                         |
+| Status             | Use-case **Partial**; real-LLM Implementable bar open; Fake CI ≠ end-user proof — **not** “no templates”                                                                                                                                                                                          |
 
 ### 7. Run lifecycle
 
@@ -161,8 +229,12 @@ These four are **not** the same thing.
 - **Can:** Harness builtins + `permission.ask` Allow/Deny for those builtins.
   Wired pack / MCP tools (including memory writes and **Langflower Tools**)
   do **not** ask — authoring the edge is consent. Write Allow does **not**
-  grant bash. Agents receive **McpHandle**s; system MCP starts only for ids
-  enabled on nodes in the active workflow.
+  grant bash. MCP **nodes** wire `tools` → agent `tools` (`ToolHandle[]`).
+  Optional **Tool collection** (`common-tool-collection`) can merge several
+  `tools` wires into one before the agent. Direct multi-wire into the agent
+  still works. System MCP from `langflower.jsonc` starts only for ids enabled
+  on nodes in the active workflow; those tools land on `EC.toolHandles`,
+  never as raw config.
 - **Can:** `compile_custom_nodes` exists only when **Langflower Tools**
   (`common-langflower-tools`) is wired into that agent’s `tools` port
   (starter Helper / Writer). Same intent as Custom → **Update**. Recompile
@@ -180,16 +252,21 @@ These four are **not** the same thing.
 ### 9. Sub-Agent and swarm
 
 Sub-Agent is an **explicit canvas node** for **control and observability**
-(own toolLog/response, visible spawn, `nodeId` filter) — not magic inside one
-LLM turn.
-
-- **Can:** First-class Sub-Agent node + spawn registration / `subagentResult`.
-  Default swarm spawns are **serial**. Wiki/memory create (`kb-create`) uses
-  **serial** scoped spawns driven by a persisted work queue — not parallel
+(own toolLog/response, visible specialist) — not magic inside one LLM turn.
+
+- **Can:** First-class Sub-Agent node. Wire Sub-Agent
+  `subagent-registration` → parent `tools` (one edge). The parent calls the
+  specialist tool (`Writer(subagent)` / `toolId` `Writer_subagent`) with a
+  `task`
+  (optional `skillId` from the Inspector Skills enum). That call closes the
+  parent work-log visit; the specialist streams as its own card. Default swarm
+  invokes are **serial**. Wiki/memory create (`kb-create`) uses **serial**
+  scoped specialist calls driven by a persisted work queue — not parallel
   whole-repo fan-out.
 - **Cannot / not yet:** Hide Sub-Agent work only inside a single LLM turn with
   no graph node (anti-pattern). Parallel fan-out as the **default**. Nested
-  **workflow files** (far future).
+  **workflow files** (far future). Do not look for `spawn_subagent` or
+  registration / spawn / result ports — those wires are gone.
 
 ### 10. Other demos
 
@@ -201,8 +278,9 @@ LLM turn.
   `kb-create` (index with `glob` → `history/work-queue.md` → serial
   Explorer/Composer units into `core/*` + `modules/*`) and `kb-navigate`.
   Managed markdown under `.langflower/memory/` (also reachable with harness
-  file tools). No vector KB / embedding as base
-  ([ADR-033](../../../../../docs/ADR.md#adr-033--markdown-memory-tools-no-embedding-as-base)).
+  file tools). **Embeddings** catalog nodes + Settings default embedding model
+  are shipped for API checks and pack **`EmbedHandle`** wiring — separate from
+  vector KB ([ADR-033](../../../../../docs/ADR.md#adr-033--markdown-memory-tools-no-embedding-as-base)).
   Obsidian vault helpers are **not** shipped (TBD-007).
 - **skill-refining:** CLI eval + `skillPath` / harness `read`; no canvas
   `skill-refining.json` demo.
@@ -218,15 +296,18 @@ When the user asks to “create a project wiki”, “build a knowledge base”,
   → Orchestrator (`common-openai-llm` + builtins `glob`/`read`/`grep` + wired
   `common-memory-tools`) → Sub-Agents Explorer (read) + Composer (write) →
   `common-review` with readiness criteria → Finish. Persist a work queue in
-  memory **before** deep survey; `spawn_subagent` **one unit at a time**.
+  memory **before** deep survey; call the Explorer / Composer specialist
+  tools **one unit at a time**.
 - **Cannot:** Recommend one LLM that “reads the whole repo once and dumps a
-  wiki”. Claim vector/embedding KB as base. Claim Obsidian vault helpers as
-  shipped.
+  wiki”. Claim Obsidian vault helpers as shipped. For semantic search over
+  markdown, point at **hello-embed** (`kb-ingest` / `kb-rag`) rather than
+  inventing catalog embedding-KB nodes.
 
 ### 11. Custom nodes
 
 - **Can:** **TypeScript** via `@langflower/node-sdk` — first-class language;
-  `tsc` / IDE types act as compile-time validators. After file changes call
+  `tsc` / IDE types act as compile-time validators. **`langflower start`**
+  compiles packs under `.langflower/nodes/`. After file changes call
   **`compile_custom_nodes`** (no args) or Custom → **Update** — same
   composer. On starter you already have the tool (Langflower Tools wired).
   Stop is not required for already-placed custom types (hot-swap).
@@ -235,6 +316,10 @@ When the user asks to “create a project wiki”, “build a knowledge base”,
   auto-place or auto-wire them mid-run.
   Packs under `.langflower/nodes/<pack>/`; user runs `npm install` in the pack
   when adding author deps. See `instructions.md` and `nodes/my-nodes/README.md`.
+  Pack `tsconfig.json` gates compile (`tsc --noEmit`). `from './file.ts'`
+  requires `"allowImportingTsExtensions": true` next to `"noEmit": true`
+  (hello-embed); otherwise the pack does not compile. Extensionless imports
+  (`my-nodes`) do not need the flag.
   Nodes may **intentionally keep in-memory internal state across runs**
   (Stop / done / Start) until the user loads another workflow or shuts down
   Langflower — not the same as Checkpoint resume after process kill.
@@ -248,10 +333,12 @@ When the user asks to “create a project wiki”, “build a knowledge base”,
 
 When the user asks to add or change a custom node from this starter chat:
 
-1. Spawn Writer (or edit `.langflower/nodes/<pack>/*.ts` yourself).
+1. Call Writer (or edit `.langflower/nodes/<pack>/*.ts` yourself).
 2. Call **`compile_custom_nodes`** (no args). Report `status` / `nodeTypes` /
    `errors` from the tool text. Pack failures also write
-   `COMPILATION_ERRORS.md`.
+   `COMPILATION_ERRORS.md`. If tsc rejects `.ts` import paths, add
+   `allowImportingTsExtensions` next to `noEmit` in the pack `tsconfig.json`
+   (copy hello-embed), then compile again.
 3. **Already on the canvas** → live now, no Stop. **New type** → user places
    it from Custom and wires it; this tool does not drop nodes on the canvas.
 4. If a custom tools pack is already wired into this agent, you may call those

package/vendor/server/skeleton/skills/langflower-helper/architecture.md

@@ -5,7 +5,8 @@ this file over inventing infrastructure.
 
 ## What it is
 
-- Local, **project-scoped** coding agent.
+- Local, **folder-scoped reactive node graph**. The LLM is a node, not the
+  product.
 - The **workflow graph** is the pipeline law (hard harness): stages and edges
   are authored; the model does not freely skip QA/review/gates outside the
   graph.
@@ -76,7 +77,15 @@ Project product data for Langflower lives under **`.langflower/`**.
 
 - LLM / agent nodes use **skills** and harness tools as wired in the graph.
 - **Sub-Agent** is an **explicit canvas node** for control and observability
-  (own toolLog/response, visible spawn) — not hidden work inside one LLM turn.
+  (own toolLog/response). Wire `subagent-registration` into the parent
+  `tools` — not hidden work inside one LLM turn. The announced tool is
+  `{name}(subagent)` (`toolId` slug `Name_subagent`). Calling that tool closes
+  the parent work-log visit; the specialist streams as its own card, and
+  the parent continues in a new visit below. Optional **Tool collection**
+  (`common-tool-collection`) can merge several `tools` wires; direct
+  multi-wire into the agent still works. Extra empty canvas slots on
+  `multi` ports (`feedback` merge, `tools` combine) and Router channels
+  (`ch` / `ch@1`) are intentional fan-in — not cloned ports.
 - **Graph order** stages the pipeline; the model does not invent the stage
   sequence outside the graph.
 - Project memory / wiki create is **queue-driven**: index with harness `glob`,
@@ -88,10 +97,12 @@ Project product data for Langflower lives under **`.langflower/`**.
 
 - Custom nodes use the same **`@langflower/node-sdk`** path as built-ins.
 - **TypeScript** is first-class; `tsc` / IDE types act as compile-time gates.
-  After file changes call `compile_custom_nodes` (only if **Langflower
-  Tools** is wired — starter Helper / Writer already are) or Custom →
-  **Update**. Same composer: typecheck + bundle + hot-swap live custom
-  instances + refresh the Custom palette.
+  `langflower start` compiles packs. After file changes call
+  `compile_custom_nodes` (only if **Langflower Tools** is wired — starter
+  Helper / Writer already are) or Custom → **Update**. Same composer:
+  typecheck + bundle + hot-swap live custom instances + refresh the Custom
+  palette. Pack `from './x.ts'` needs `allowImportingTsExtensions` +
+  `noEmit` in pack `tsconfig.json` or `tsc --noEmit` fails (hello-embed seed).
   Stop is not required for already-placed custom types.
   An already-wired custom tools pack can be invoked later in the same run
   after compile. Do not auto-place or auto-wire a new type mid-run.

package/vendor/server/skeleton/skills/langflower-helper/layout.md

@@ -7,7 +7,10 @@ Facts for UI chrome and on-disk paths. Prefer this file over guessing.
 - **Topbar** — workflow list (switch / create / rename as shipped), gear →
   **Settings**.
 - **Left palette** — built-in nodes; **Custom** packs; **Update** reloads
-  custom packs after disk changes.
+  custom packs after disk changes. Collapse with `<<` on the Palette title
+  row; restore with floating `>>` at the canvas top-left. Visibility is
+  project `paletteVisible` (missing key = shown) and is allowed during a
+  run.
 - **Center** — canvas (nodes, edges, selection).
 - **Right aside** — mutually exclusive modes: **feed** | **inspector** |
   **Settings**. Opening Settings (gear or empty-provider onboarding) swaps out
@@ -17,21 +20,25 @@ Facts for UI chrome and on-disk paths. Prefer this file over guessing.
 
 ## Where can I…?
 
-| Goal                                   | Where                                                                                                                                                                                                                                                                                                                |
-| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Change provider / API key              | Gear → **Settings** (right aside; Global auto-opens when none configured), or edit `.langflower/langflower.jsonc` (prefer `{env:VAR}`)                                                                                                                                                                               |
-| Start a Chat Input graph               | Composer **Start** — not plain **Run** (Run stays disabled for those graphs)                                                                                                                                                                                                                                         |
-| See run output / stream                | Right aside **feed**                                                                                                                                                                                                                                                                                                 |
-| Answer HITL / send into a waiting node | Composer + feed context                                                                                                                                                                                                                                                                                              |
-| Allow or Deny `permission.ask`         | Composer permission controls                                                                                                                                                                                                                                                                                         |
-| Soft-pause last feed agent / continue  | Composer **Pause** (per-node) / Send or Resume (soft pause ≠ Hard Stop)                                                                                                                                                                                                                                              |
-| Hard-stop a run                        | Composer **Stop**                                                                                                                                                                                                                                                                                                    |
-| Edit selected node params / ports      | Select node → right aside **inspector** (not Settings)                                                                                                                                                                                                                                                               |
-| Add or reload custom nodes             | Pack under `.langflower/nodes/<pack>/`. On starter, Helper / Writer call `compile_custom_nodes` (Langflower Tools is wired). Else Custom → **Update**. Hot-swap already-placed types; already-wired custom tools work later in the same run. New types: user places from Custom (no auto-place / auto-wire mid-run). |
-| Switch workflow                        | Topbar workflow list                                                                                                                                                                                                                                                                                                 |
-| Open Settings without leaving canvas   | Gear — Settings in right aside                                                                                                                                                                                                                                                                                       |
-| Find sample coding graphs              | Skeleton / demo-project workflow files — **manual copy** into project, then load → Start. No Sample workflows catalog UI.                                                                                                                                                                                            |
-| Project instructions for agents        | `.langflower/instructions.md`                                                                                                                                                                                                                                                                                        |
+| Goal                                             | Where                                                                                                                                                                                                                                                                                                                                                                          |
+| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Change provider / API key                        | Gear → **Settings** (right aside; Global auto-opens when none configured), or edit `.langflower/langflower.jsonc` (prefer `{env:VAR}`)                                                                                                                                                                                                                                         |
+| Start a Chat Input graph                         | Composer **Start** — not plain **Run**. Prefill lives on the node; Stop then Start reuses it.                                                                                                                                                                                                                                                                                  |
+| See run output / stream                          | Right aside **feed**                                                                                                                                                                                                                                                                                                                                                           |
+| Answer HITL / send into a waiting node           | Composer + feed context                                                                                                                                                                                                                                                                                                                                                        |
+| Allow or Deny `permission.ask`                   | Composer permission controls                                                                                                                                                                                                                                                                                                                                                   |
+| Soft-pause last feed agent / continue            | Composer **Pause** (per-node) / Send or Resume (soft pause ≠ Hard Stop)                                                                                                                                                                                                                                                                                                        |
+| Hard-stop a run                                  | Composer **Stop**                                                                                                                                                                                                                                                                                                                                                              |
+| Edit selected node params / ports                | Select node → right aside **inspector** (not Settings). Read-only while a run is active — Stop first.                                                                                                                                                                                                                                                                          |
+| See what a built-in node does                    | Hover a palette row (popover) **or** select the node → inspector **description** (markdown).                                                                                                                                                                                                                                                                                   |
+| Add a node from the palette                      | Drag from the left palette onto the canvas. Disabled while a run is active (`cursor-not-allowed`) — Stop first.                                                                                                                                                                                                                                                                |
+| Hide / show the node palette                     | Palette title `<<` / canvas `>>`. Shared across tabs; stored as `paletteVisible` in project `langflower.jsonc`. Allowed during a run.                                                                                                                                                                                                                                          |
+| Add or reload custom nodes                       | Pack under `.langflower/nodes/<pack>/`. Server start compiles existing packs. After file changes: on starter, Helper / Writer call `compile_custom_nodes` (Langflower Tools is wired). Else Custom → **Update**. Hot-swap already-placed types; already-wired custom tools work later in the same run. New types: user places from Custom (no auto-place / auto-wire mid-run). |
+| Switch workflow                                  | Topbar workflow list. Load / New / Copy / rename / Delete are locked while a run is active — Stop first.                                                                                                                                                                                                                                                                       |
+| Open Settings without leaving canvas             | Gear — Settings in right aside                                                                                                                                                                                                                                                                                                                                                 |
+| Find sample coding graphs                        | Skeleton / demo-project workflow files — **manual copy** into project, then load → Start. No Sample workflows catalog UI.                                                                                                                                                                                                                                                      |
+| Why extra empty ports on Helper / tools / Router | Those inputs are `multi`. Wiring one slot shows the next free slot. **Feedback** = several sources (HITL + auto-review). **Tools** = several packs. **Router** = extra channels (`ch` / `ch@1`). Leave the empty row unwired.                                                                                                                                                  |
+| Project instructions for agents                  | `.langflower/instructions.md`                                                                                                                                                                                                                                                                                                                                                  |
 
 ## On-disk `.langflower/` map
 
@@ -40,7 +47,7 @@ Facts for UI chrome and on-disk paths. Prefer this file over guessing.
 | `langflower.jsonc` | Providers, secrets refs, project config                                                       |
 | `workflows/`       | Saved workflow graphs                                                                         |
 | `skills/`          | Agent skills (`langflower-helper/`, `langflower-node-writer/`, `langflower-workflow-writer/`) |
-| `nodes/`           | Custom node packs (e.g. `my-nodes/`)                                                          |
+| `nodes/`           | Custom node packs (`my-nodes/`, sample `hello-embed/`)                                        |
 | `instructions.md`  | Project-level agent instructions                                                              |
 | `runs/`            | Run artifacts / checkpoints when created                                                      |
 | `logs/`            | Server bridge diagnostic JSONL logs when the server runs                                      |

package/vendor/server/skeleton/skills/langflower-node-writer/SKILL.md

@@ -20,6 +20,10 @@ You help the user write **custom nodes** for Langflower.
   starter, Writer has it because **Langflower Tools** is wired. Custom →
   **Update** is the same composer. Failures land in `COMPILATION_ERRORS.md`.
   Do **not** only remind the user to click Update.
+- Pack `tsconfig.json` is the `tsc --noEmit` gate. `from './lib/x.ts'`
+  requires `"allowImportingTsExtensions": true` next to `"noEmit": true`
+  (copy `hello-embed/tsconfig.json`). Without it the pack does not compile.
+  Extensionless imports (`my-nodes`) do not need the flag.
 - Langflower does **not** auto-`npm install` pack dependencies.
 - Do **not** claim you can place a newly compiled type on the canvas or wire
   it mid-run. Already-placed types hot-swap; already-wired custom tools can
@@ -28,7 +32,8 @@ You help the user write **custom nodes** for Langflower.
 ## Contract (do not invent forks)
 
 - Default pack: `.langflower/nodes/my-nodes/` (one folder = one `package.json`).
-- Prefer **`defineNode`** for sync/Promise nodes. Use
+- Prefer **`defineNode`** for sync/Promise nodes (`execute` stamps pending
+  on outputs). Use
   **`defineToolRegistrations`** for LLM-callable `ToolHandle` packs on a
   `tools` port. Use **`defineReactiveNode`** only when exclusive multi-output
   branches, streams, or advanced bind wiring are required.
@@ -64,3 +69,5 @@ You help the user write **custom nodes** for Langflower.
 - `.langflower/nodes/my-nodes/README.md`
 - Seed demos: `git-diff.ts` (`defineNode`), `git-diff-tool.ts`
   (`defineToolRegistrations`), `review-gate.ts` (`defineReactiveNode`)
+- Multi-file + `.ts` imports: `.langflower/nodes/hello-embed/` (`tsconfig.json`
+  already has `allowImportingTsExtensions`)

package/vendor/server/skeleton/skills/langflower-workflow-writer/SKILL.md

@@ -2,7 +2,8 @@
 name: Langflower workflow writer
 description: >-
     Guides authors writing and editing `.langflower/workflows/*.json` graphs
-    (catalog node types, real ports, Soft↔Hard loops, Sub-Agent L0 wiring).
+    (catalog node types, real ports, Soft↔Hard loops, Sub-Agent
+    `subagent-registration` wiring).
 ---
 
 # Langflower workflow writer
@@ -55,11 +56,13 @@ Schema: `.langflower/schemas/workflow.schema.json`. Samples:
 | Node type                               | Key ports                                                                                                                                                                                                              |
 | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `common-chat-input`                     | out `message` (no wireable in)                                                                                                                                                                                         |
-| `common-openai-llm` / `common-fake-llm` | in `userPrompt`, `systemPrompt`, `feedback`, `subagentRegistration`, `subagentResult`; out `response`, `subagent`, …                                                                                                   |
+| `common-openai-llm` / `common-fake-llm` | in `userPrompt`, `systemPrompt`, `feedback`, `tools`; out `response`, `toolLog`, …                                                                                                                                     |
+| `common-mcp-stdio` / `common-mcp-http`  | out **`tools`** — wire into an agent `tools` port (not a separate `mcp` port)                                                                                                                                          |
+| `common-tool-collection`                | in **`tools`** (multi combine) → out **`tools`** — optional hub; duplicate `toolId` last-wins. Direct pack → agent still OK                                                                                            |
 | `common-hitl-review-gate`               | in `result`; out `response`, `feedback`                                                                                                                                                                                |
 | `common-merge`                          | in/out **`value`** only (not `step` / `output`)                                                                                                                                                                        |
-| `common-review`                         | in `task`, `result`, `systemPrompt`; out `response`, `feedback`                                                                                                                                                        |
-| `common-sub-agent`                      | out `registration`, `result`; in `task`, `systemPrompt`                                                                                                                                                                |
+| `common-review`                         | in `task`, `result`, `systemPrompt`, `tools`; out `response`, `feedback`                                                                                                                                               |
+| `common-sub-agent`                      | out **`subagent-registration`** (one specialist handle) → parent `tools`; in `systemPrompt`, `tools`                                                                                                                   |
 | `common-finish`                         | in `value`                                                                                                                                                                                                             |
 | `common-string`                         | in/out `value`                                                                                                                                                                                                         |
 | `common-langflower-tools`               | out **`tools`** only — wire into an agent `tools` port to opt in to **`compile_custom_nodes`** (unsafe; starter Helper / Writer already wired). Not ambient. Canvas add/remove node or edge tools are **not** shipped. |
@@ -75,13 +78,14 @@ Typical HITL revise loop:
 Do **not** feed Merge output into both gates and LLM feedback on every tick
 without a clear phase split.
 
-## Sub-Agent L0 (registration + spawn)
+## Sub-Agent (one registration wire)
 
 Mirror `.langflower/workflows/kb-navigate.json`:
 
-- Sub-Agent `registration` → parent `subagentRegistration`
-- Parent `subagent` → Sub-Agent `task`
-- Sub-Agent `result` → parent `subagentResult`
+- Sub-Agent `subagent-registration` → parent `tools`
+- Parent calls the specialist tool (`task`, optional `skillId` enum)
+- Do **not** draw `registration` / `subagent` / `task` / `result` /
+  `subagentResult` — those ports are gone
 
 ## Load repair (product fact)
 

package/vendor/server/skeleton/workflows/kb-create.json

@@ -60,7 +60,7 @@
 					"maxFeedbackTurns": 8
 				},
 				"inputs": {
-					"systemPrompt": "You are the Orchestrator for building a DETAILED project memory map (project wiki) under `.langflower/memory/`.\n\nGoal: grounding a coding agent can use to implement features without rediscovering the repo. A thin whole-repo skim is NOT enough.\n\n## Required memory layout (all under `.langflower/memory/`)\n\n1) `core/overview.md` — purpose, primary user, ships vs not, how to run\n2) `core/layout.md` — directory / package map with ownership\n3) `core/architecture.md` — runtime flow, boundaries, key ADRs / invariants\n4) `core/build-test.md` — install, build, typecheck, unit vs integration, verify\n5) `core/entrypoints.md` — CLI / server / UI / MCP paths and ports\n6) `core/conventions.md` — coding rules agents must follow\n7) `modules/<area>.md` — one file per major package/area (responsibility, layout, contracts, neighbors, pitfalls)\n8) `history/work-queue.md` — indexed work units (Pending / In progress / Done)\n9) `history/build-log.md` — chronological survey/write notes (append_memory_log)\n\nOptional when material exists: `core/config.md`, `core/workflows-skills.md`.\n\n## Process (STRICT order — serial spawn_subagent)\n\n### Phase A — Index first (before any deep Explorer/Composer spawn)\n\n1) Use `glob` + `read` on package.json workspaces, top-level dirs, README*, AGENTS.md, docs/** (or equivalents). List every workspace package / major area and each mandatory `core/*` topic.\n2) Persist `.langflower/memory/history/work-queue.md` via create_memory_file / update_memory_section with ## Pending, ## In progress, ## Done. Each Pending item: id, path(s) to survey, target memory file (`modules/<area>.md` or `core/<name>.md`), status.\n3) Do NOT spawn Explorer/Composer for a vague “survey the whole repo” after the queue exists.\n\n### Phase B — One-unit loop\n\n1) Pick ONE Pending unit → move to In progress in work-queue.md.\n2) spawn_subagent Explorer with a task that names ONLY that unit (paths, expected depth, target memory file).\n3) spawn_subagent Composer for ONLY that unit’s target file/sections (pass Explorer findings).\n4) Mark the unit Done; append_memory_log on history/build-log.md.\n5) Repeat until Pending is empty (or explicit justified skips with evidence in the queue).\n\n### Phase C — Exit / Review feedback\n\n- Emit readiness only when Pending is empty AND mandatory files have real ## sections with concrete paths/commands/types.\n- Module pages MUST cover every indexed package/area from the queue.\n- On Review feedback: re-open specific queue items — do not restart a vague whole-repo pass.\n- Cite evidence (paths + section headings) in the readiness report."
+					"systemPrompt": "You are the Orchestrator for building a DETAILED project memory map (project wiki) under `.langflower/memory/`.\n\nGoal: grounding a coding agent can use to implement features without rediscovering the repo. A thin whole-repo skim is NOT enough.\n\n## Required memory layout (all under `.langflower/memory/`)\n\n1) `core/overview.md` — purpose, primary user, ships vs not, how to run\n2) `core/layout.md` — directory / package map with ownership\n3) `core/architecture.md` — runtime flow, boundaries, key ADRs / invariants\n4) `core/build-test.md` — install, build, typecheck, unit vs integration, verify\n5) `core/entrypoints.md` — CLI / server / UI / MCP paths and ports\n6) `core/conventions.md` — coding rules agents must follow\n7) `modules/<area>.md` — one file per major package/area (responsibility, layout, contracts, neighbors, pitfalls)\n8) `history/work-queue.md` — indexed work units (Pending / In progress / Done)\n9) `history/build-log.md` — chronological survey/write notes (append_memory_log)\n\nOptional when material exists: `core/config.md`, `core/workflows-skills.md`.\n\n## Process (STRICT order — serial specialist tool calls)\n\n### Phase A — Index first (before any deep Explorer/Composer spawn)\n\n1) Use `glob` + `read` on package.json workspaces, top-level dirs, README*, AGENTS.md, docs/** (or equivalents). List every workspace package / major area and each mandatory `core/*` topic.\n2) Persist `.langflower/memory/history/work-queue.md` via create_memory_file / update_memory_section with ## Pending, ## In progress, ## Done. Each Pending item: id, path(s) to survey, target memory file (`modules/<area>.md` or `core/<name>.md`), status.\n3) Do NOT call Explorer/Composer for a vague “survey the whole repo” after the queue exists.\n\n### Phase B — One-unit loop\n\n1) Pick ONE Pending unit → move to In progress in work-queue.md.\n2) Call the Explorer specialist tool with a task that names ONLY that unit (paths, expected depth, target memory file).\n3) Call the Composer specialist tool for ONLY that unit’s target file/sections (pass Explorer findings).\n4) Mark the unit Done; append_memory_log on history/build-log.md.\n5) Repeat until Pending is empty (or explicit justified skips with evidence in the queue).\n\n### Phase C — Exit / Review feedback\n\n- Emit readiness only when Pending is empty AND mandatory files have real ## sections with concrete paths/commands/types.\n- Module pages MUST cover every indexed package/area from the queue.\n- On Review feedback: re-open specific queue items — do not restart a vague whole-repo pass.\n- Cite evidence (paths + section headings) in the readiness report."
 				},
 				"ui": {
 					"position": {
@@ -212,48 +212,6 @@
 				"toNodeId": "review",
 				"toPort": ["tools", 0]
 			},
-			{
-				"edgeId": "e-reg-explorer",
-				"fromNodeId": "explorer",
-				"fromPort": ["registration", 0],
-				"toNodeId": "orchestrator",
-				"toPort": ["subagentRegistration", 0]
-			},
-			{
-				"edgeId": "e-reg-composer",
-				"fromNodeId": "composer",
-				"fromPort": ["registration", 0],
-				"toNodeId": "orchestrator",
-				"toPort": ["subagentRegistration", 1]
-			},
-			{
-				"edgeId": "e-spawn-explorer",
-				"fromNodeId": "orchestrator",
-				"fromPort": ["subagent", 0],
-				"toNodeId": "explorer",
-				"toPort": ["task", 0]
-			},
-			{
-				"edgeId": "e-spawn-composer",
-				"fromNodeId": "orchestrator",
-				"fromPort": ["subagent", 0],
-				"toNodeId": "composer",
-				"toPort": ["task", 0]
-			},
-			{
-				"edgeId": "e-result-explorer",
-				"fromNodeId": "explorer",
-				"fromPort": ["result", 0],
-				"toNodeId": "orchestrator",
-				"toPort": ["subagentResult", 0]
-			},
-			{
-				"edgeId": "e-result-composer",
-				"fromNodeId": "composer",
-				"fromPort": ["result", 0],
-				"toNodeId": "orchestrator",
-				"toPort": ["subagentResult", 1]
-			},
 			{
 				"edgeId": "e-orch-review-result",
 				"fromNodeId": "orchestrator",
@@ -281,6 +239,20 @@
 				"fromPort": ["response", 0],
 				"toNodeId": "done",
 				"toPort": ["value", 0]
+			},
+			{
+				"edgeId": "e-tools-explorer",
+				"fromNodeId": "explorer",
+				"fromPort": ["subagent-registration", 0],
+				"toNodeId": "orchestrator",
+				"toPort": ["tools", 1]
+			},
+			{
+				"edgeId": "e-tools-composer",
+				"fromNodeId": "composer",
+				"fromPort": ["subagent-registration", 0],
+				"toNodeId": "orchestrator",
+				"toPort": ["tools", 2]
 			}
 		]
 	}