flowexec · jahvon · Jul 11, 2025 · Jul 11, 2025
@@ -0,0 +1 @@
+github: jahvon
@@ -1,16 +1,95 @@
 <p align="center"><a href="https://flowexec.io"><img src="docs/_media/logo.png" alt="flow" width="200"/></a></p>
 
-<br>
-
 <p align="center">
     <a href="https://img.shields.io/github/v/release/flowexec/flow"><img src="https://img.shields.io/github/v/release/flowexec/flow" alt="GitHub release"></a>
     <a href="https://pkg.go.dev/github.com/flowexec/flow"><img src="https://pkg.go.dev/badge/github.com/flowexec/flow.svg" alt="Go Reference"></a>
+    <a href="https://discord.gg/CtByNKNMxM"><img src="https://img.shields.io/badge/discord-join%20community-7289da?logo=discord&logoColor=white" alt="Join Discord"></a>
+    <a href="https://github.com/flowexec/flow"><img alt="GitHub Repo stars" src="https://img.shields.io/github/stars/flowexec/flow"></a>
 </p>
 
 <p align="center">
-    <b>flow</b> is a customizable and interactive CLI automation tool designed to streamline how you manage and run local 
-    development and operations workflows. It uses executable YAML configurations, organized across workspaces and namespaces, 
-    for tasks like running scripts, transforming APIs, or generating file systems from templates. <i>Charming</i>, interactive TUI included!
+    <b>flow</b> is your personal workflow hub - organize automation across all your projects with built-in secrets, templates, and cross-project composition.
+    Define workflows in YAML, discover them visually, and run them anywhere.
 </p>
 
-<p align="center"><b>Learn more at <a href="https://flowexec.io">flowexec.io</a></b></p>
+---
+
+## Quick Start
+
+```bash
+# Install
+curl -sSL https://raw.githubusercontent.com/flowexec/flow/main/scripts/install.sh | bash
+
+# Create your first workflow
+flow workspace add my-project . --set
+echo 'executables:
+  - verb: run
+    name: hello
+    exec:
+      cmd: echo "Hello from flow!"' > hello.flow
+
+# Run it
+flow sync
+flow run hello
+```
+
+## Key Features
+
+flow complements existing CLI tools by adding multi-project organization, built-in security, and visual discovery to your automation toolkit.
+
+- **Workspace organization** - Group and manage workflows across multiple projects
+- **Encrypted secret vaults** - Multiple backends (AES, Age, external tools)
+- **Interactive discovery** - Browse, search, and filter workflows visually
+- **Flexible execution** - Serial, parallel, conditional, and interactive workflows
+- **Workflow generation** - Create projects and workflows from reusable templates
+- **Composable workflows** - Reference and chain workflows within and across projects
+
+<p align="center"><img src="docs/_media/demo.gif" alt="flow" width="1600"/></p>
+
+## Example Workflows
+
+```yaml
+# api.flow
+executables:
+  - verb: deploy
+    name: staging
+    serial:
+      execs:
+        - cmd: npm run build
+        - cmd: docker build -t api:staging .
+        - ref: shared-tools/k8s:deploy-staging
+        - cmd: curl -f https://api-staging.example.com/health
+
+  - verb: backup
+    name: database
+    exec:
+      params:
+        - secretRef: database-url
+          envKey: DATABASE_URL
+      cmd: pg_dump $DATABASE_URL > backup-$(date +%Y%m%d).sql
+```
+
+```bash
+# Run workflows
+flow deploy staging
+flow backup database
+
+# Visual discovery
+flow browse
+```
+
+## Documentation
+
+**Complete documentation at [flowexec.io](https://flowexec.io)**
+
+- [Installation](https://flowexec.io/#/installation) - Multiple installation methods
+- [Quick Start](https://flowexec.io/#/quickstart) - Get up and running in 5 minutes
+- [Core Concepts](https://flowexec.io/#/guide/concepts) - Understand workspaces, executables, and vaults
+- [User Guides](https://flowexec.io/#/guide/README) - Comprehensive guides for all features
+
+## Community
+
+- [Discord Community](https://discord.gg/CtByNKNMxM) - Get help and share workflows
+- [Issue Tracker](https://github.com/flowexec/flow/issues) - Report bugs and request features
+- [Examples Repository](https://github.com/flowexec/examples) - Real-world workflow patterns
+- [Contributing Guide](https://flowexec.io/#/development) - Help make flow better
@@ -3,24 +3,34 @@
 <p align="center">
   <a href="https://img.shields.io/github/v/release/flowexec/flow"><img src="https://img.shields.io/github/v/release/flowexec/flow" alt="GitHub release"></a>
   <a href="https://pkg.go.dev/github.com/flowexec/flow"><img src="https://pkg.go.dev/badge/github.com/flowexec/flow.svg" alt="Go Reference"></a>
+  <a href="https://discord.gg/CtByNKNMxM"><img src="https://img.shields.io/badge/discord-join%20community-7289da?logo=discord&logoColor=white" alt="Join Discord"></a>
+  <a href="https://github.com/flowexec/flow"><img alt="GitHub Repo stars" src="https://img.shields.io/github/stars/flowexec/flow"></a>
 </p>
 
-flow is a customizable and interactive CLI tool designed to streamline how you manage and run local development and 
-operations workflows.
+flow is your personal **workflow hub** - organize automation across all your projects with built-in secrets, templates, 
+and cross-project composition. Go beyond task running to workflow management that scales with your development ecosystem.
 
-**This project is currently in beta and documentation is a work in progress.** Contributions and feedback are welcome.
+#### _Why flow?_ <!-- {docsify-ignore} -->
 
-#### _Features_ <!-- {docsify-ignore} -->
+- **Unified automation hub**: Organize workflows across all your projects in one place
+- **Built-in security**: Encrypted vaults keep your secrets safe and shareable
+- **Cross-project power**: Reference workflows from other projects and share common tools
+- **Template-driven**: Generate new projects and workflows from reusable templates
+- **Visual discovery**: Browse and search workflows across your entire development ecosystem
 
-- **Task Runner**: Easily define, manage, and run your tasks (called [executables](guide/executable.md)) from the command line.
-- **Secret Vault**: Store sensitive secrets in a secure local [vault](guide/secret.md#vault-setup).
-- **Template Generator**: Generate executables and workspace scaffolding with [flow file templates](guide/templating.md).
-- **TUI Library**: Explore and run executables from the interactive and searchable TUI [library](cli/flow_browse.md).
-- **Executable Organizer**: Group, reference, and search for executables by workspace, namespace, verbs, and tags.
-- **Input Handler**: Pass values into executables with environment variables defined by secrets, command-line args, or interactive prompts.
-- **Customizable TUI**: Personalize your [TUI experience](guide/interactive.md) with settings for log formatting, log archiving, and execution notifications, and more.
+#### _Core Capabilities_ <!-- {docsify-ignore} -->
+
+- **Workflow Management**: Define, organize, and run workflows across multiple projects
+- **Secure Secret Storage**: Built-in encrypted vaults with multiple backend options
+- **Project Generation**: Create new projects and workflows from customizable templates
+- **Cross-Project Composition**: Reference and share workflows between different projects
+- **Visual Workflow Browser**: Discover and run workflows with powerful filtering and search
+- **Flexible Configuration**: YAML-based definitions with arguments, secrets, and conditional logic
+
+**Ready to organize your automation?** → [Install flow](installation.md) → [Quick start guide](quickstart.md)
 
 ---
 
 <p align="center"><img src="_media/demo.gif" width="1600"></p>
 
+Browse examples in the [examples repo](https://github.com/flowexec/examples) and [flow project](https://github.com/flowexec/flow/tree/main/.execs)
@@ -1,11 +1,11 @@
 <img src="_media/icon.png" alt="flow"/>
 
-# flow <small>beta</small>
+# flow
 
 > _Interactive CLI automation that flows with you._
 
 - Define your _executables_ in YAML
-- Run and manage them from the TUI
+- Browse and execute with ease
 
 [GitHub](https://github.com/flowexec/flow)
 [Get Started](README.md)
@@ -1,22 +1,6 @@
-- [Home](README.md "flow documentation")
 - [Install](installation.md "Installation guide")
-
-- Getting Started
-    - [Quick start](quickstart.md "Quick start guide")
-    - [Workspaces](guide/workspace.md "Managing workspaces")
-    - [Executables](guide/executable.md "Managing executables")
-    - [Secrets vault](guide/secret.md "Using the secrets vault")
-
-- Advanced Features
-    - [Templating](guide/templating.md "Using flowfile templates")
-    - [Managing state](guide/state.md "Managing executable state")
-    - [Conditional execution](guide/conditional.md "Conditional execution")
-    - [Customizing the TUI](guide/interactive.md "Customizing the interactive UI")
-    - [Integrations](guide/integrations.md "Integration")
-
-- Reference
-
-    - [CLI Commands](cli/README.md "Command line interface reference")
-    - [Configuration Files](types/README.md "Configuration file reference")
-
+- [Quick Start](quickstart.md "Quick start guide")
+- [User Guides](guide/README.md "Complete guides for mastering flow automation")
+- [CLI Reference](cli/README.md "Command line interface reference")
+- [Configuration Reference](types/README.md "YAML configuration file reference")
 - [Contributing](development.md "Development guide")
@@ -1,15 +1,13 @@
-- [Home](../README.md "flow documentation")
-- [Install](../installation.md "Installation guide")
-- [Quick Start](../quickstart.md "Quick start guide")
+- [← Back to Home](../README.md "flow documentation")
 
-- Reference
-    - [CLI commands](README.md "Command line interface reference")
+- CLI Reference
+    - [flow](README.md "Command line interface reference")
         - [flow exec](flow_exec.md)
-        - [flow library](flow_library.md)
+        - [flow browse](flow_browse.md)
         - [flow template](flow_template.md)
         - [flow config](flow_config.md)
         - [flow workspace](flow_workspace.md)
         - [flow secret](flow_secret.md)
+        - [flow vault](flow_vault.md)
         - [flow sync](flow_sync.md)
         - [flow logs](flow_logs.md)
-    - [Configuration files](../types/README.md "Configuration file reference")
@@ -1,76 +1,135 @@
-# flow Development
+# Contributing to flow
 
 [![Go Report Card](https://goreportcard.com/badge/github.com/flowexec/flow)](https://goreportcard.com/report/github.com/flowexec/flow)
 [![Go Reference](https://pkg.go.dev/badge/github.com/flowexec/flow.svg)](https://pkg.go.dev/github.com/flowexec/flow)
-[![GitHub branch status](https://img.shields.io/github/checks-status/flowexec/flow/main)](https://github.com/flowexec/flow/actions?query=branch%3Amain)
+[![GitHub branch check runs](https://img.shields.io/github/check-runs/flowexec/flow/main)](https://github.com/flowexec/flow/actions?query=branch%3Amain)
 [![Codecov](https://img.shields.io/codecov/c/github/flowexec/flow)](https://app.codecov.io/gh/flowexec/flow)
 
-Before getting started, please read the [Code of Conduct](../.github/CODE_OF_CONDUCT.md) and [Contributing Guidelines](../.github/CONTRIBUTING.md).
+This document provides an overview of how to contribute to the flow project, including setting up your development environment, understanding the project structure, and running tests.
 
-flow is written in [Go](https://golang.org/). See the [go.mod](../go.mod) file for the current Go version used in 
-building the project.
+Before getting started, please read our [Code of Conduct](https://github.com/flowexec/flow/blob/main/.github/CODE_OF_CONDUCT.md) and [Contributing Guidelines](https://github.com/flowexec/flow/blob/main/.github/CONTRIBUTING.md).
 
-## Getting Started
+**Ways to Contribute**
 
-Before developing on this project, you will need to make sure you have the latest `flow` version installed.
-Refer to the [Installation](installation.md) section for more information.
+- **Report bugs** - [Open an issue](https://github.com/flowexec/flow/issues/new) with reproduction steps
+- **Suggest features** - Share ideas for new functionality
+- **Improve documentation** - Fix typos, add examples, or clarify explanations
+- **Write code** - Fix bugs, implement features, or optimize performance
+- **Share examples** - Contribute to the [examples repository](https://github.com/flowexec/examples)
 
-After cloning the repository, you can start using the below commands after registering the repo workspace:
+## Quick Start 
+
+**Prerequisites**
+
+- **Go** - See [go.mod](https://github.com/flowexec/flow/blob/main/go.mod) for the required version
+- **flow CLI** - Install the [latest version](installation.md) before developing
 
 ```sh
-flow workspace create flow <repo-path>
+# Clone and set up the repository
+git clone https://github.com/flowexec/flow.git
+cd flow
+
+# Register the repo as a flow workspace
+flow workspace add flow . --set
+
+# Install development dependencies
+flow install tools
+
+# Verify everything works
+flow validate
 ```
 
-### Development Executables
+## Development Executables
 
-The `flow` project contains a few development executables that can be run locally. After registering the repo
-workspace, you can run the following commands:
+The flow project uses flow itself for development! Here are the key commands:
 
 ```sh
-# Install Go tool dependencies
-flow install tools
-
 # Build the CLI binary
-flow build binary <output-path>
+flow build binary ./bin/flow
 
-# Validate code changes (runs tests, linters, codegen, etc)
+# Run all validation (tests, linting, code generation)
 flow validate
 
-# Only generate code
-flow generate
+# Run specific checks
+flow test all             # All tests
+flow generate             # Code generation
+flow run lint             # Linting only
 
-# Only run tests
-flow test all
+# Install/update Go tools
+flow install tools
 ```
 
-### Working with generated types
+## Project Structure
 
-The `flow` project uses [go-jsonschema](github.com/atombender/go-jsonschema) with [go generate](https://blog.golang.org/generate) 
-to generate Go types from JSON schema files (defined in YAML). If you need to make changes to the generated types 
-(found in the `types` package), you should update the associated `*schema.yaml` file and run the flow `run generate` executable
-or go generate directly.
+```
+flow/
+├── .execs/             # Development workflows
+├── cmd/                # CLI entry point
+├── docs/               # Documentation
+├── internal/           # Core application logic
+│   ├── cache/          # Executable and workspace caching logic
+│   ├── context/        # Global application context
+│   ├── io/             # Terminal user interface and I/O
+│   ├── runner/         # Executable execution engine
+│   ├── services/       # Business logic services
+│   ├── templates/      # Templating system for workflows
+│   └── vault/          # Secret management
+├── tests/              # CLI end-to-end test suite
+└── types/              # Generated types from schemas
+```
 
-Note that go generate alone does not update generated documentation. 
-Be sure to regenerate the JSON schema files and markdown documentation before submitting a PR.
+_Some directories are omitted for brevity._
 
-### Working with tuikit
+## Working with Generated Code
 
-The `flow` project uses the [tuikit](tuikit.md) framework for building the terminal UI.
-Contributions to the components and helpers in `tuikit` are welcome.
+flow uses code generation extensively:
+
+### Go CLI Type Generation <!-- {docsify-ignore} -->
+
+Types are generated from YAML schemas using [go-jsonschema](https://github.com/atombender/go-jsonschema):
 
-_You should test all tuikit changes with a local flow build before submitting a PR._
-
 ```sh
-  go mod edit -replace github.com/flowexec/tuikit=../tuikit
+# Regenerate types after schema changes
+flow generate cli
+```
+
+**Important**: When modifying types, edit the `schemas/*.yaml` files, not the generated Go files in `types/`.
+
+### Documentation Generation <!-- {docsify-ignore} -->
+
+CLI and type documentation is generated automatically:
+
+```sh
+# Updates both CLI docs and type reference docs
+flow generate docs
+```
+
+## TUI Development
+
+flow uses [tuikit](tuikit.md) for terminal interface development:
+
+**Local Development**
+
+```sh
+# Link to local tuikit for development
+go mod edit -replace github.com/flowexec/tuikit=../tuikit
+
+# Test TUI changes
+flow build binary ./bin/flow-dev
+./bin/flow-dev browse
 ```
 
 ## Development Tools
 
-Required tools for development:
+### Required Tools <!-- {docsify-ignore} -->
+
+These are installed automatically by `flow install tools`:
+
+- [mockgen](https://github.com/uber-go/mock) - Generate test mocks
+- [golangci-lint](https://golangci-lint.run/) - Code linting
+- [go-jsonschema](https://github.com/atombender/go-jsonschema) - Generate Go types from YAML schemas
 
-- [mockgen](https://github.com/uber-go/mock) for generating test mocks
-- [golangci-lint](https://golangci-lint.run/) for linting
+### Additional Tools <!-- {docsify-ignore} -->
 
-Other tools used in the project:
-- [goreleaser](https://goreleaser.com/) for releasing the project
-- [ginkgo](https://onsi.github.io/ginkgo/) and [gomega](https://onsi.github.io/gomega/) for testing
+- [goreleaser](https://goreleaser.com/) - Release automation
+- [ginkgo](https://onsi.github.io/ginkgo/) - BDD testing framework