@synergenius/flow-weaver 0.33.1 → 0.44.0

package/README.md

@@ -1,317 +1,225 @@
 # Flow Weaver
 
 [![npm version](https://img.shields.io/npm/v/@synergenius/flow-weaver?style=flat)](https://www.npmjs.com/package/@synergenius/flow-weaver)
-[![npm downloads](https://img.shields.io/npm/dw/@synergenius/flow-weaver?style=flat)](https://www.npmjs.com/package/@synergenius/flow-weaver)
 [![CI](https://img.shields.io/github/actions/workflow/status/synergenius-fw/flow-weaver/ci.yml?branch=main&style=flat)](https://github.com/synergenius-fw/flow-weaver/actions/workflows/ci.yml)
-[![Tests](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/moraispgsi/305430ef59a51d0a58eb61fefdfbe634/raw/flow-weaver-test-count.json&style=flat)](https://github.com/synergenius-fw/flow-weaver/actions/workflows/ci.yml)
-[![Coverage](https://img.shields.io/codecov/c/github/synergenius-fw/flow-weaver?style=flat)](https://codecov.io/gh/synergenius-fw/flow-weaver)
-[![License: Flow Weaver Library License](https://img.shields.io/badge/License-Flow%20Weaver%20Library-blue?style=flat)](./LICENSE)
 [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D22-green?style=flat)](https://nodejs.org)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue?style=flat)](./LICENSE)
 
-**Design agent workflows in conversation. The compiled output is yours.**
+**A deterministic TypeScript workflow compiler. You describe a workflow with JSDoc annotations. It compiles to a standalone TypeScript function you own.**
 
-[**flowweaver.ai**](https://flowweaver.ai) · [**Studio**](https://flowweaver.ai/studio) · [**Features**](https://flowweaver.ai/features) · [**Discord**](https://discord.gg/6Byh3ur2bk) · [**npm**](https://www.npmjs.com/package/@synergenius/flow-weaver)
+Flow Weaver turns annotated functions into an execution graph and generates the workflow body in place. The compiled file imports nothing from Flow Weaver: it is plain TypeScript you can read, review and keep, and it is yours under any licence you like. The code that calls it hands it one small object, the runtime, and the compiled file exports the helper that builds it. Running what the compiler produced needs nothing from the package, gates included.
 
----
+Workflows are plain `.ts` files, so everything you already do with code applies: Git, code review, tests, linting, CI. Build them by hand the way you write JSDoc, or drive the whole compiler through MCP tools from Claude Code, Cursor, VS Code, Windsurf, or any MCP-compatible editor.
 
-Flow Weaver is a TypeScript workflow compiler. Define workflows with JSDoc annotations in your existing codebase, compile to standalone TypeScript functions with zero runtime dependencies, and deploy to any serverless target. The compiled output has no dependency on Flow Weaver. You own it.
+## Install
 
-Build AI agent workflows, data pipelines, or automation scripts through natural language using MCP tools in Claude Code, Cursor, Windsurf, VS Code, JetBrains, Codex, or any MCP-compatible editor. Or write them by hand with annotations the same way you write JSDoc today.
+Requires Node.js **22+**.
 
-## About me & my vision
+```bash
+npm install @synergenius/flow-weaver
+```
 
-Hey, I am [Ricardo Morais](https://linkedin.com/in/moraispgsi), the project's founder and owner. 
+This installs the `fw` CLI, the MCP server, the local console, and the library, all in one package.
 
-I have always wondered why Visual Programming never took off. After understanding why I tried to address most of the concerns from the development community:
-  - No lock-in: code is compiled and yours, not dependent on this library. You can remove the annotation after compiling and the file is standalone.
-  - The code is the source of truth, visual part runs on top, this allows you to create your workflows visually in the Studio, at the end of the day it is just plain Typescript code that you or any LLM can understand and iterate.
-  - It being just code opens a lot of doors for you, like using Git for version control, doing all sort of stuff you already do with code like testing, linting, automating, everything.
-  - In the era of LLMs and agents, being able to have that control is crucial, it is not a black box, you can see everything and so can your assistant.
+## Quick start
 
-As of now this is a solo project and I am building it in the open. There is a lot to do and rough edges to smooth out. If you run into issues or have questions, the [Discord](https://discord.gg/6Byh3ur2bk) is the best place to reach out. Every issue and question gets a response. I genuinely want to hear from you.
+```bash
+npx fw init my-project        # a project: a workflow, a runner that calls it, the config
+cd my-project && npm install
+npm start                     # run the compiled workflow
+npx fw console --open         # see it as a process; run it, and answer its gates, from the browser
+```
 
-If this resonates with what you have been looking for, give it a try and let me know how it goes. Stars, feedback, and honest criticism all help equally.
+On any workflow file:
 
-## Project Status
+```bash
+npx fw validate src/my-project-workflow.ts
+npx fw run src/my-project-workflow.ts --params '{"data":{"message":"hi"}}'   # no compile needed to try it
+npx fw compile src/my-project-workflow.ts                                    # generate the standalone body in place
+```
 
-Flow Weaver is in **beta**. The compiler, validator, CLI, and MCP tools are stable and thoroughly tested. The test suite covers thousands of cases across parsing, compilation, validation, diffing, and deployment. CI runs on every commit.
+Run `fw --help` or `fw <command> --help` for full options.
 
-**Flow Weaver Studio**, the browser-based visual IDE, is the next major milestone and is being actively built. Core editing (canvas, terminal, diagnostics) is live today. The visual debugger, AI chat assistant, version history, and deployment dashboard are in progress. You can follow development on Discord or in the [GitHub releases](https://github.com/synergenius-fw/flow-weaver/releases).
+## How workflows are defined
 
-Breaking changes may still occur between minor versions during beta. Pin your version in `package.json` if stability matters for your project.
+A **node type** is a plain function annotated `@flowWeaver nodeType`. Its ports are inferred from the signature: each parameter is an input, each field of the returned object an output. Most node types are pure `@expression` functions.
 
-## Capabilities
+A **workflow** is an exported function annotated `@flowWeaver workflow`. `@param` declares its inputs (`Start`), `@returns` its outputs (`Exit`), `@node` creates instances, and `@path` wires the route, connecting each data port to the nearest earlier step with a matching output. The body is a stub. The compiler fills it in between markers and leaves everything else untouched.
 
-**Annotation-driven workflows:** Define node graphs directly in TypeScript using JSDoc annotations. No YAML, no JSON configs, no separate workflow files. Your workflows live in `.ts` files, version-controlled alongside your code.
+```typescript
+/**
+ * @flowWeaver nodeType
+ * @expression
+ * @input name - Name to greet
+ * @output message - Greeting message
+ */
+function greet(name: string): string {
+  return `Hello, ${name}!`;
+}
 
-**Zero-dependency compiled output:** The compiler generates a self-contained TypeScript function. No runtime to install in production, no SDK to import, no vendor lock-in. Delete the package after compiling and the output still runs.
+/**
+ * @flowWeaver nodeType
+ * @expression
+ * @input message - Text to transform
+ * @output result - Uppercased text
+ */
+function shout(message: string): string {
+  return message.toUpperCase();
+}
 
-**AI-native editing:** MCP tools expose the full compiler, validator, debugger, and diagram surface to any MCP-compatible editor. Scaffold a project, add nodes, wire connections, validate, compile, run, and diff through conversation.
+/**
+ * @flowWeaver workflow
+ * @param name - Name to greet
+ * @returns result - Uppercased greeting
+ * @node greeter greet
+ * @node transform shout
+ * @path Start -> greeter -> transform -> Exit
+ */
+export function greeting(
+  execute: boolean,
+  params: { name: string },
+): { onSuccess: boolean; onFailure: boolean; result: string } {
+  throw new Error('generated body was not installed');
+}
+```
 
-**Structural validation:** Type checking across port connections, graph topology analysis, agent safety rules, and breaking change detection. Runs in CI, on every save, or on demand. Errors include source locations, fix suggestions, and documentation links.
+That is a complete workflow. `fw compile` reads the annotations, builds the graph, and installs the real body.
 
-**Step-through debugging:** Set breakpoints on nodes, step through execution node by node, inspect variables mid-run, and resume from checkpoints. Variable injection available through MCP tools.
+## The local console
 
-**Semantic diffing:** Compare workflow versions at the graph level instead of text diffs. Impact analysis categorizes every change as critical, breaking, minor, or cosmetic. Know exactly what changed and whether it matters.
+`fw console` opens a local web app over a project's workflows. Every workflow appears as a process, with its issues and code, live runs with each step's values, gates answered from a form built from the port's type, a step-through debugger, and a semantic diff between versions. Runs you start there use the same coordinator the MCP tools and `fw serve` use, so a run paused for approval can be answered from the browser, from an assistant, or over HTTP, interchangeably.
 
-**Deploy anywhere:** Export to Inngest, AWS Lambda, Vercel, Cloudflare Workers, GitHub Actions, or GitLab CI. Or serve workflows over HTTP with built-in framework adapters for Next.js, Express, Hono, Fastify, and Remix.
+```bash
+fw console --open
+```
 
-**Extensible pack system:** Node types, deploy targets, CLI commands, and MCP tools are contributed by npm packages. Install community packs or build and publish your own.
+Its Project page is the front door: the project's HTTP server with Start, Stop and its logs, the declared endpoints, the agent profiles, the editors that have the MCP server, the environment checks, and every run waiting for a person. It binds to `127.0.0.1:4311` and re-reads files as you save them.
 
-**OpenClaw integration:** Use Flow Weaver inside [OpenClaw](https://openclaw.ai) with the native plugin. Build deterministic workflows through conversation. [Plugin](https://clawhub.ai/plugins/%40synergenius%2Fflow-weaver-openclaw) | [npm](https://www.npmjs.com/package/@synergenius/flow-weaver-openclaw) 🦞
+## AI-native editing
 
-## Quick Start
+The MCP server exposes the full compiler, validator, debugger, and diagram surface to any MCP-compatible editor. Scaffold, add nodes, wire connections, validate, compile, run, and diff, all through conversation.
 
 ```bash
-npm install @synergenius/flow-weaver
-npx flow-weaver init my-agent
-npx flow-weaver compile my-agent.ts
-npx flow-weaver run my-agent.ts
+fw mcp-setup     # register the server with Claude, Cursor, VS Code, Windsurf, Codex, or OpenClaw
+fw mcp-server    # or start it manually
 ```
 
-The CLI scaffolds a project, compiles annotations into a runnable workflow, and executes it. Run `fw --help` for the full command reference. The example below shows a more complete workflow built through conversation.
-
-## See It in Action
-
-The conversation below shows [Weaver](https://github.com/synergenius-fw/flow-weaver-pack-weaver), an optional AI bot that drives Flow Weaver through natural language. It handles scaffolding, modification, validation, compilation, execution, and deployment. Install it with `fw market install @synergenius/flow-weaver-pack-weaver`, or use the MCP tools directly from your editor without Weaver.
-
-> **You:** Build a support agent that classifies messages and either auto-replies or escalates.
-
-> **Weaver:** Created `support-agent.ts`. Four nodes, one workflow.
->
-> ```
-> Workflow: supportAgent
->
-> Nodes (4):
->   classify  [classifyIntent]  IN: message  OUT: context
->   route     [routeAction]     IN: context, execute  OUT: context, onSuccess, onFailure
->   reply     [llmReply]        IN: context  OUT: reply
->   esc       [escalate]        IN: context  OUT: ticket, assignee
->
-> Paths (2):
->   Start -> classify -> route -> reply -> Exit
->   Start -> classify -> route -> esc -> Exit
-> ```
-
-> **You:** Show me the graph.
-
-> **Weaver:**
->
-> ```
->  ┌───────┐    ┌─────────────────┐    ┌──────────────┐    ┌───────────┐    ┌──────┐
->  │ Start │━━━▶│ Classify Intent │━━━▶│ Route Action │━━━▶│ LLM Reply │━━━▶│ Exit │
->  └───────┘    └─────────────────┘    └──────────────┘    └───────────┘    └──────┘
->
->  Parallel: Escalate
-> ```
-
-> **You:** Compile it.
-
-> **Weaver:** Done. Zero runtime deps. The output is a standalone TypeScript function you own.
-
-> **You:** Validate.
-
-> **Weaver:**
->
-> ```
-> ✓ 1 valid, 2 warnings in 312ms
-> ```
->
-> Structural, agent safety, and CI rules. All checked.
-
-> **You:** Run it with "I need an urgent refund".
-
-> **Weaver:**
->
-> ```
-> classify: → SUCCEEDED (0ms)
-> route:    → SUCCEEDED (0ms)
-> reply:    → CANCELLED
-> esc:      → SUCCEEDED (0ms)
-> ✓ Workflow "supportAgent" completed in 2ms
->
-> Result: { ticket: "ESC-1773950738529", assignee: "support-team" }
-> ```
-
-> **You:** Commit it.
-
-> **Weaver:** Committed to `main`. It's a `.ts` file in your repo. Version-controlled like everything else.
-
-> **You:** Now add sentiment analysis before routing.
-
-> **Weaver:** Done. Here's what changed:
->
-> ```
-> [BREAKING] +1 types, ~1 types, +1 nodes, +5 conns, -2 conns
->
-> + analyzeSentiment
-> ~ routeAction (+inputs: sentiment)
-> + sentiment (instance)
-> + classify.context → sentiment.context
-> + sentiment.sentiment → route.sentiment
-> ```
-
-> **You:** Where does this deploy?
-
-> **Weaver:** Anywhere TypeScript runs. Or generate boilerplate:
->
-> ```
-> fw export support-agent.ts --target vercel
-> fw export support-agent.ts --target lambda
-> fw export support-agent.ts --target cloudflare
-> fw export support-agent.ts --target inngest
-> ```
-
-## How Workflows Are Defined
-
-Workflows are TypeScript functions annotated with JSDoc. You write plain functions for each node, and the annotations describe how they connect.
-
-The function signature is the source of truth. Input parameters become input ports, return object fields become output ports. Every function has an `execute` boolean that controls whether it runs or passes through, and returns `onSuccess`/`onFailure` for branching. Expression nodes (marked with `@expression`) skip the execute/branching pattern and map return fields directly to outputs.
-
-The `@flowWeaver workflow` block wires node instances together. `@node` creates an instance of a node type, `@connect` wires ports between nodes, and `@path` is shorthand for a linear route. `Start` and `Exit` are virtual nodes representing the workflow's inputs and outputs.
-
-The compiler reads these annotations, builds the execution graph, and generates the body in place between markers. Everything outside the markers stays untouched. Node type functions are never modified.
+## Durable workflows
 
-```typescript
-/**
- * @flowWeaver nodeType
- * @expression
- * @input message - The support message
- * @output context - Classified context
- */
-function classifyIntent(message: string): { context: SupportContext } {
-  const intent = /refund|cancel/i.test(message) ? 'billing' : 'general';
-  return { context: { message, intent, priority: 'normal' } };
-}
+A **gate** is a node where the run stops and hands control to something outside it: a person approving (`@durableGate approval`), an external system answering (`waitForEvent`), or an AI agent doing a task (`waitForAgent`). The run returns a continuation and the process is free to exit. Later, any process resumes from exactly that node with the answer. `fw create workflow approval <file>` writes one to start from.
 
-// routeAction, llmReply, and escalate are defined the same way:
-// plain functions with @flowWeaver nodeType annotations.
+Paused runs live in a store: the project's `.fw/runs` directory (the project being the nearest folder with a `package.json`), or a store of your own behind a nine-method interface. `fw console`, `fw serve`, the MCP tools and your own code through `createLocalCoordinator` can all drive the same runs, so a gate reached anywhere is answered anywhere. (`fw run` is for workflows without gates. It has nowhere to keep a run between one gate and the next.) A host with no package at all works too: the compiled file throws a `DurableGateYield` carrying the continuation, and exports `acceptContinuation` to take it back later. See `fw docs library`.
 
+An agent gate can be answered without anyone watching: a **profile** in `.flowweaver/agents.yaml` names a model (Anthropic, any OpenAI-compatible server including a local one, or the Claude Code CLI) and the environment variable that holds its key. The model gets the gate's inputs and one tool shaped from the gate's output type, and the run resumes with what it returns. `fw agents --init` writes the starter file. The console's Agents page edits it with a form.
+
+## Workflows as endpoints
+
+A workflow declares its route, and `fw serve` mounts it:
+
+```typescript
 /**
  * @flowWeaver workflow
- * @node classify classifyIntent
- * @node route routeAction
- * @node reply llmReply
- * @node esc escalate
- * @path Start -> classify -> route -> reply -> Exit
- * @path route:fail -> esc -> Exit
- * @connect Start.message -> classify.message
- * @connect classify.context -> route.context
- * @param message - The support message
- * @returns reply - Generated reply
- * @returns ticket - Escalation ticket
+ * @http POST /reviews
+ * @http GET /reviews/:path
+ * @param path - The file
+ * @param text - Its contents
+ * @returns report - The review
  */
-export async function supportAgent(
+export async function reviewFile(
   execute: boolean,
-  params: { message: string },
-): Promise<{
-  onSuccess: boolean;
-  onFailure: boolean;
-  reply: string | null;
-  ticket: string | null;
-}> {
-  // @flow-weaver-body-start
-  // Generated by the compiler. Do not edit.
-  // @flow-weaver-body-end
+  params: { path: string; text: string },
+): Promise<{ onSuccess: boolean; onFailure: boolean; report: string }> {
+  throw new Error('generated body was not installed');
 }
 ```
 
-## CLI Reference
-
-| Command | Description |
-|---------|-------------|
-| `fw init` | Scaffold a new project with presets and templates |
-| `fw compile` | Compile workflow files to standalone TypeScript |
-| `fw validate` | Validate workflows without compiling |
-| `fw run` | Execute a workflow with optional debug mode |
-| `fw watch` | Recompile on file changes |
-| `fw dev` | Watch + compile + run loop |
-| `fw describe` | Output workflow structure as JSON, text, Mermaid, ASCII, or paths |
-| `fw diagram` | Generate SVG, HTML, or ASCII diagrams |
-| `fw diff` | Semantic diff between two workflow versions |
-| `fw export` | Export to a deploy target (Inngest, Lambda, Vercel, Cloudflare, etc.) |
-| `fw serve` | Start an HTTP server exposing workflows as endpoints |
-| `fw modify` | Programmatic graph mutations (addNode, removeNode, connect, etc.) |
-| `fw mcp-server` | Start the MCP server for AI editor integration |
-| `fw mcp-setup` | Auto-configure MCP for Claude, Cursor, VS Code, Windsurf, or Codex |
-| `fw docs` | Browse bundled reference documentation |
-
-Run `fw --help` or `fw <command> --help` for full options.
+Parameters bind from the path, the query or the JSON body. The answer is the workflow's return ports: `200` on success, `422` on the failure path, `202` with a `Location` to poll when a gate pauses the run. An `Idempotency-Key` makes a retry the same run. A `callback` route posts the final response to the caller. `/openapi.json` describes all of it.
 
-## Flow Weaver Studio (Beta)
+The same handler mounts in your own server (Node, Express, Fastify, or a fetch host) from `@synergenius/flow-weaver/server`:
 
-A browser-based visual IDE for building workflows. Canvas editor, integrated terminal, real-time diagnostics, and the full CLI available in the cloud.
+```typescript
+import { createServer } from 'node:http';
+import { createWorkflowApi } from '@synergenius/flow-weaver/server';
 
-Studio is in beta. Core editing is live. The visual debugger, AI chat assistant, version history, and deployment dashboard are being actively developed and will ship incrementally. The cloud platform is not yet production-ready, and paid plans are not available yet. Use it to explore and experiment, but expect rough edges.
+const api = createWorkflowApi({ dir: './workflows', token: process.env.FW_SERVE_TOKEN });
+createServer(api.node()).listen(3000);   // or, in Express: app.use('/api', api.express())
+```
 
-[Open Studio](https://flowweaver.ai/studio) · [Learn more](https://flowweaver.ai/features)
+## Using it as a library
 
-## Weaver (Experimental)
+The compiled file imports nothing from the package. The code that *calls* it needs one object, the runtime, and the compiled file exports the helper that builds it:
 
-Weaver is an optional AI bot that automates the full workflow lifecycle. Give it a task in natural language and it plans, scaffolds, compiles, validates, and fixes issues in a loop until the workflow is correct. It connects to Anthropic, Claude CLI, or GitHub Copilot CLI.
+```typescript
+import { greeting, createWorkflowRuntime } from './my-workflow';
 
-- `weaver bot "create a greeting workflow"` handles a task end-to-end with plan approval
-- `weaver run workflow.ts` executes a workflow with an AI agent channel attached
-- `weaver session` polls a task queue continuously for automated pipelines
-- `weaver swarm start` runs multiple bot instances in parallel, with an orchestrator dispatching tasks across them
+const runtime = createWorkflowRuntime({ runId: 'run-1', workflowId: 'greeting' });
+const result = await greeting(true, { name: 'Alice' }, runtime);
+// result.result === 'HELLO, ALICE!'
+```
 
-Weaver is itself built as a set of Flow Weaver workflows. Run `weaver eject` to get a local copy you can customize.
+The package exports the same `createWorkflowRuntime`, built from the same source, for code that already depends on it. Parse, validate, compile, query, and diff are all available programmatically from `@synergenius/flow-weaver/api`. `@synergenius/flow-weaver/coordinator` starts and resumes gated runs from code and takes a run store of your own. `@synergenius/flow-weaver/server` is the HTTP handler behind `fw serve`. See `fw docs library` for the full surface and entry points.
 
-```bash
-fw market install @synergenius/flow-weaver-pack-weaver
-```
+## CLI reference
 
-> **Weaver is experimental.** The bot, session, and swarm modes work and are being used internally, but the APIs and behavior may change between releases. Weaver is not required to use Flow Weaver. The compiler, CLI, and MCP tools are the stable foundation and work independently.
+| Command | Description |
+|---------|-------------|
+| `fw init` | Scaffold a new project |
+| `fw validate` | Validate workflows without compiling |
+| `fw compile` / `fw strip` | Compile workflows to standalone TypeScript, or remove the generated code |
+| `fw run` | Execute a workflow without gates directly |
+| `fw watch` / `fw dev` | Recompile (and run) on file changes |
+| `fw console` | Open the local operator console |
+| `fw agents` | The agent profiles that answer agent gates, and a starter file |
+| `fw describe` | Output workflow structure (JSON, text, Mermaid, ASCII) |
+| `fw diagram` | Draw a workflow as an SVG or terminal diagram |
+| `fw artifact` | Export a workflow as a shareable page, PDF, or SVG |
+| `fw diff` | Semantic diff between two workflow versions |
+| `fw modify` | Programmatic graph mutations |
+| `fw create` / `fw templates` | Create workflows or nodes from templates |
+| `fw status` / `fw implement` | Report which stub nodes are still unimplemented, and replace a stub with a real function |
+| `fw migrate` | Rewrite workflow files in the current syntax |
+| `fw serve` | Serve the workflows' declared routes and run resources over HTTP, where gated runs pause and resume |
+| `fw export` / `fw openapi` | Export to a deploy target, or generate an OpenAPI spec |
+| `fw market` | Discover, install, and publish marketplace packs |
+| `fw doctor` | Check the project environment |
+| `fw mcp-server` / `fw mcp-setup` | Start or configure the MCP server |
+| `fw docs` / `fw grammar` | Browse the bundled reference documentation, or print the annotation grammar |
+| `fw context` | Build a context bundle of the docs for an LLM |
+
+## Extending with packs
+
+Node types, deploy targets, CLI commands, and MCP tools are contributed by npm packages ("packs"). Discover, install, and publish them with `fw market`, or build your own. See `fw docs marketplace`.
 
 ## Documentation
 
-Reference documentation is bundled with the CLI. Run `fw docs` to browse topics, or `fw docs <topic>` to read a specific one:
+Reference documentation ships with the CLI:
 
 ```bash
-fw docs list                    # List all topics
-fw docs tutorial                # Step-by-step first workflow guide
-fw docs concepts                # Core concepts
-fw docs jsdoc-grammar           # Annotation syntax reference
-fw docs cli-reference           # Full CLI command reference
-fw docs search <query>          # Search across all docs
+fw docs list             # list all topics
+fw docs tutorial         # first-workflow walkthrough
+fw docs concepts         # the core model
+fw docs jsdoc-grammar    # annotation syntax
+fw docs search <query>   # search across all docs
 ```
 
-**Online resources:**
+Upgrading between versions: [MIGRATION.md](./MIGRATION.md) explains how `fw migrate` rewrites workflow files in the current syntax.
 
-- [Features](https://flowweaver.ai/features)
-- [Compare with Alternatives](https://flowweaver.ai/compare)
-- [License](https://flowweaver.ai/license)
+## Project status
 
-## Community
+Flow Weaver is in **beta**. The compiler, validator, CLI, console, and MCP tools are stable and thoroughly tested. CI runs the full test suite on Linux for every push and pull request, and a smoke test installs the packed CLI on Linux, macOS, and Windows on every push to `main`. Breaking changes may still occur between minor versions during beta, so pin your version if stability matters.
 
-Flow Weaver is built and maintained by a solo developer. If you try it, find a bug, or just want to talk about workflows, the [Discord](https://discord.gg/6Byh3ur2bk) is open. Every message gets read and responded to, usually within a day.
+## Community
 
-If something breaks, [open an issue](https://github.com/synergenius-fw/flow-weaver/issues). Bug reports with reproduction steps get prioritized. Feature requests are welcome too.
+Built and maintained by [Ricardo Morais](https://github.com/moraispgsi). Found a bug or have a question? [Open an issue](https://github.com/synergenius-fw/flow-weaver/issues) or start a [Discussion](https://github.com/synergenius-fw/flow-weaver/discussions).
 
 ## Contributing
 
-See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+See [CONTRIBUTING.md](./CONTRIBUTING.md).
 
 ## License
 
-Licensed under the [Flow Weaver Library License](https://flowweaver.ai/license). See [LICENSE](./LICENSE).
-
-The license is designed to be generous for the vast majority of users while protecting the project's IP. Here is what it means in practice:
-
-**Use freely:**
-- Install, compile, validate, run, and deploy workflows in any project
-- All compiled output is fully yours with no restrictions or attribution required
-- Use in CI/CD pipelines and build systems
-- Host internally for organizations with 15 or fewer people
-- Include as a dependency in larger products where Flow Weaver is not the primary value
-
-**Requires a commercial license:**
-- Internal hosting for organizations with more than 15 people
-- Building a hosted or standalone workflow authoring product
-- Offering Flow Weaver capabilities as a managed service to third parties
+Flow Weaver is licensed under the [Apache License 2.0](./LICENSE).
 
-**Never permitted:**
-- Using source code, tests, documentation, or outputs as AI/ML training data to replicate the functionality
-- Extracting specifications to build competing software
+What the compiler produces is yours. Compiled workflows, generated code and diagrams, including the execution engine the compiler copies into each compiled file, may be used, modified and distributed under any terms you choose, without attribution. See [NOTICE](./NOTICE).
 
-If you are unsure whether your use case needs a commercial license, reach out at support@synergenius.pt. The answer is probably "you're fine."
+Support and enterprise agreements: support@synergenius.pt.

package/dist/agent/agent-loop.d.ts

@@ -1,10 +1,12 @@
 /**
- * Provider-agnostic agent loop — streams LLM responses, collects tool calls,
+ * Provider-agnostic agent loop. It streams LLM responses, collects tool calls,
  * executes them via a caller-provided executor, and iterates.
  *
  * The loop never touches provider internals. Adding a new provider (Codex,
- * Gemini, etc.) requires zero loop changes — just implement AgentProvider.
+ * Gemini, etc.) requires zero loop changes: just implement AgentProvider.
  */
 import type { AgentProvider, AgentMessage, ToolDefinition, ToolExecutor, AgentLoopOptions, AgentLoopResult } from './types.js';
+/** A tool result within the cap, with a note saying what was left out. */
+export declare function truncateToolResult(result: string, cap?: number): string;
 export declare function runAgentLoop(provider: AgentProvider, tools: ToolDefinition[], executor: ToolExecutor, messages: AgentMessage[], options?: AgentLoopOptions): Promise<AgentLoopResult>;
 //# sourceMappingURL=agent-loop.d.ts.map

package/dist/agent/cli-session.d.ts

@@ -1,5 +1,5 @@
 /**
- * Persistent CLI session manager — eliminates cold-start delay by keeping
+ * Persistent CLI session manager that eliminates cold-start delay by keeping
  * the Claude CLI process alive between messages.
  *
  * Instead of spawning a new CLI process per message (~5s cold start + MCP
@@ -44,7 +44,7 @@ export declare class CliSession {
     matchesOptions(other: CliSessionOptions): boolean;
     /**
      * Inject a mock child process for testing.
-     * @internal — test only
+     * @internal test only
      */
     _injectForTest(child: ChildProcess): void;
     /**
@@ -55,7 +55,7 @@ export declare class CliSession {
      * Send a user message and stream back events.
      * Auto-respawns if the process has died.
      *
-     * Phase 1.3: Concurrent send() guard — throws if a previous turn is still active.
+     * Phase 1.3: Concurrent send() guard that throws if a previous turn is still active.
      * The activeTurn lock is claimed synchronously BEFORE any async work (spawn)
      * to prevent TOCTOU races.
      */