From 1590858f79c345648ac51bdf233fd0705b725367 Mon Sep 17 00:00:00 2001
From: Simon Ordish <71426+ordishs@users.noreply.github.com>
Date: Thu, 30 Oct 2025 14:33:17 +0100
Subject: [PATCH 1/2] docs(CLAUDE): add project summary and core capabilities

---
 .github/CLAUDE.md | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/.github/CLAUDE.md b/.github/CLAUDE.md
index cee1d09..6929bfa 100644
--- a/.github/CLAUDE.md
+++ b/.github/CLAUDE.md
@@ -1,5 +1,19 @@
 # CLAUDE.md
 
+## 📦 Project Summary
+
+**go-subtree** is a high-performance Go library for managing Bitcoin SV (BSV) merkle tree subtree structures. It provides efficient tools for organizing transactions hierarchically, essential for block assembly, transaction validation, and merkle proof generation in BSV blockchain infrastructure.
+
+### Core Capabilities
+- **Subtree Management**: Create and manipulate merkle trees with dynamic node addition/removal
+- **Merkle Operations**: Generate merkle proofs, calculate roots, handle incomplete trees
+- **Serialization**: Binary format support for storage and transmission with streaming deserialization
+- **Transaction Tracking**: Link full transaction data to tree nodes, track inpoints and conflicts
+- **Performance**: Zero runtime dependencies, allocation-free operations, parallel tree computation
+
+### Target Use Cases
+Bitcoin block construction, mempool management, SPV proof generation, teranode transaction organization.
+
 ## 🤖 Welcome, Claude
 
 This repository uses **`AGENTS.md`** as the single source of truth for:

From 355f11f834edb2f84bea17391ab98ca766517118 Mon Sep 17 00:00:00 2001
From: Simon Ordish <71426+ordishs@users.noreply.github.com>
Date: Thu, 30 Oct 2025 14:41:45 +0100
Subject: [PATCH 2/2] docs: add project overview and core capabilities to
 README

---
 .github/CLAUDE.md |  2 +-
 README.md         | 42 +++++++++++++++++++++++++++++++++---------
 2 files changed, 34 insertions(+), 10 deletions(-)

diff --git a/.github/CLAUDE.md b/.github/CLAUDE.md
index 6929bfa..f15c01c 100644
--- a/.github/CLAUDE.md
+++ b/.github/CLAUDE.md
@@ -12,7 +12,7 @@
 - **Performance**: Zero runtime dependencies, allocation-free operations, parallel tree computation
 
 ### Target Use Cases
-Bitcoin block construction, mempool management, SPV proof generation, teranode transaction organization.
+Bitcoin block construction, SPV proof generation, teranode transaction organization.
 
 ## 🤖 Welcome, Claude
 
diff --git a/README.md b/README.md
index 873c266..c5b0c36 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,22 @@
 # 🌿 go-subtree
 > A Go library for efficiently managing Bitcoin SV Subtree transaction structures
 
+## 📦 Overview
+
+**go-subtree** is a high-performance Go library for managing Bitcoin SV (BSV) merkle tree subtree structures. It provides efficient tools for organizing transactions hierarchically, essential for block assembly, transaction validation, and merkle proof generation in BSV blockchain infrastructure.
+
+### Core Capabilities
+- **Subtree Management**: Create and manipulate merkle trees with dynamic node addition/removal
+- **Merkle Operations**: Generate merkle proofs, calculate roots, handle incomplete trees
+- **Serialization**: Binary format support for storage and transmission with streaming deserialization
+- **Transaction Tracking**: Link full transaction data to tree nodes, track inpoints and conflicts
+- **Performance**: Zero runtime dependencies, allocation-free operations, parallel tree computation
+
+### Target Use Cases
+Bitcoin block construction, SPV proof generation, teranode transaction organization.
+
+<br/>
+
 <table>
   <thead>
     <tr>
@@ -75,15 +91,23 @@
 <br/>
 
 ## 🗂️ Table of Contents
-* [Installation](#-installation)
-* [Documentation](#-documentation)
-* [Examples & Tests](#-examples--tests)
-* [Benchmarks](#-benchmarks)
-* [Code Standards](#-code-standards)
-* [AI Compliance](#-ai-compliance)
-* [Maintainers](#-maintainers)
-* [Contributing](#-contributing)
-* [License](#-license)
+- [🌿 go-subtree](#-go-subtree)
+	- [📦 Overview](#-overview)
+		- [Core Capabilities](#core-capabilities)
+		- [Target Use Cases](#target-use-cases)
+	- [🗂️ Table of Contents](#️-table-of-contents)
+	- [📦 Installation](#-installation)
+	- [📚 Documentation](#-documentation)
+		- [🎛️ The Workflow Control Center](#️-the-workflow-control-center)
+	- [🧪 Examples \& Tests](#-examples--tests)
+	- [⚡ Benchmarks](#-benchmarks)
+		- [Benchmark Results](#benchmark-results)
+	- [🛠️ Code Standards](#️-code-standards)
+	- [🤖 AI Compliance](#-ai-compliance)
+	- [👥 Maintainers](#-maintainers)
+	- [🤝 Contributing](#-contributing)
+		- [How can I help?](#how-can-i-help)
+	- [📝 License](#-license)
 
 <br/>