From f7a4df5fb587f2ed0c78b3cb1bae169dd5751158 Mon Sep 17 00:00:00 2001
From: Chase Fleming <1666730+chasefleming@users.noreply.github.com>
Date: Mon, 3 Nov 2025 11:30:19 -0800
Subject: [PATCH 1/2] Update readme

---
 README.md | 15 ++++++---------
 1 file changed, 6 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index dc8ed2f0a..6f5c58256 100644
--- a/README.md
+++ b/README.md
@@ -1,16 +1,13 @@
 ## Flowkit Package Design
-Flowkit is a core package used by the CLI commands. It features APIs for interacting with the Flow network 
+
+Flowkit is a core package used by the CLI commands. It features APIs for interacting with the Flow network
 in the context of flow.json configuration values. Flowkit is defined by the [interface here](services.go).
 
-Flowkit contains multiple subpackages, the most important ones are: 
-- **config**: parsing and storing of flow.json values, as well as validation, 
+Flowkit contains multiple subpackages, the most important ones are:
+- **config**: parsing and storing of flow.json values, as well as validation,
 - **gateway**: implementation of Flow AN methods, uses emulator as well as Go SDK to communicate with ANs,
 - **project**: stateful operations on top of flow.json, which allows resolving imports in contracts used in deployments
 
-It is important we define clear boundaries between flowkit and other CLI packages. If we are in doubt where certain 
-methods should be implemented we must ask ourselves if the method provides value for any other consumers of the 
-pacakge or only provides utility for CLI usage, if it's only providing utility for CLI then it should be added inside 
-the internal package, instead of flowkit. If in doubt better to add things to internal package and then move to flowkit 
-if such need is identified. 
-
+## Documentation
 
+For detailed usage examples and tutorials on using Flowkit in your Go applications, see the [Flowkit documentation](https://developers.flow.com/build/tools/clients/flow-go-sdk/flowkit).

From bbfd6d9149fba3096e567a4fdb5beeae3589ff81 Mon Sep 17 00:00:00 2001
From: Chase Fleming <1666730+chasefleming@users.noreply.github.com>
Date: Mon, 3 Nov 2025 11:31:39 -0800
Subject: [PATCH 2/2] Update

---
 README.md | 53 +++++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 45 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 6f5c58256..e2cf23b16 100644
--- a/README.md
+++ b/README.md
@@ -1,13 +1,50 @@
-## Flowkit Package Design
+# Flowkit
 
-Flowkit is a core package used by the CLI commands. It features APIs for interacting with the Flow network
-in the context of flow.json configuration values. Flowkit is defined by the [interface here](services.go).
+Flowkit is a Go library for building applications that interact with the Flow blockchain. It provides high-level APIs for managing Flow projects, including working with `flow.json` configurations, deploying contracts, executing scripts, and building transactions.
 
-Flowkit contains multiple subpackages, the most important ones are:
-- **config**: parsing and storing of flow.json values, as well as validation,
-- **gateway**: implementation of Flow AN methods, uses emulator as well as Go SDK to communicate with ANs,
-- **project**: stateful operations on top of flow.json, which allows resolving imports in contracts used in deployments
+## Features
+
+- **Project Management** - Load and manage Flow project configurations (`flow.json`)
+- **Contract Deployment** - Deploy Cadence contracts to different networks
+- **Import Resolution** - Automatically resolve contract imports to blockchain addresses
+- **Multi-Network Support** - Work seamlessly with emulator, testnet, and mainnet
+- **Account Management** - Manage Flow accounts and signing keys
+- **Script Execution** - Execute Cadence scripts and build transactions
+
+## Installation
+
+```bash
+go get github.com/onflow/flowkit/v2
+```
+
+## Quick Example
+
+```go
+import "github.com/onflow/flowkit/v2"
+
+// Load your Flow project
+state, err := flowkit.Load([]string{"flow.json"}, afero.NewOsFs())
+
+// Get contracts for a network
+contracts, err := state.DeploymentContractsByNetwork(config.TestnetNetwork)
+
+// Resolve imports in your Cadence code
+importReplacer := project.NewImportReplacer(contracts, state.AliasesForNetwork(network))
+resolvedProgram, err := importReplacer.Replace(program)
+```
 
 ## Documentation
 
-For detailed usage examples and tutorials on using Flowkit in your Go applications, see the [Flowkit documentation](https://developers.flow.com/build/tools/clients/flow-go-sdk/flowkit).
+For comprehensive guides and examples, visit the [Flowkit documentation](https://developers.flow.com/build/tools/clients/flow-go-sdk/flowkit).
+
+## Package Structure
+
+Flowkit contains multiple subpackages:
+
+- **config** - Parsing and storing of `flow.json` values, as well as validation
+- **gateway** - Implementation of Flow Access Node methods, uses emulator and Go SDK to communicate with ANs
+- **project** - Stateful operations on top of `flow.json`, including import resolution for contract deployments
+- **accounts** - Account and key management
+- **transactions** - Transaction building and signing
+
+The main Flowkit interface is defined in [services.go](services.go).