diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md
index aa30090..b8f4c74 100644
--- a/.claude/CLAUDE.md
+++ b/.claude/CLAUDE.md
@@ -11,6 +11,13 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
- **[docs/REFERENCE.md](docs/REFERENCE.md)** — Comprehensive guide covering every feature with detailed examples. Point AI coding agents here.
- **[docs/overview/](docs/overview/)** — Quick overview guides (010–100) for each topic.
+### Back-to-Top Anchors
+
+Both `README.md` and `docs/REFERENCE.md` use back-to-top navigation after each main section. When adding a new numbered section to `REFERENCE.md`:
+
+1. Add `⬆️ back to top
` before the `---` that closes the section
+2. Update the Table of Contents with the new entry
+
## Common Commands
```bash
diff --git a/README.md b/README.md
index c683b2c..4c791b7 100644
--- a/README.md
+++ b/README.md
@@ -91,7 +91,7 @@ You can also check the [examples](examples) directory for more simple examples o
> **🤖 AI Agents:** Point your coding assistant to [`docs/REFERENCE.md`](docs/REFERENCE.md) for complete API knowledge and patterns, or explore the [AI-Powered Wiki](https://deepwiki.com/solid-process/solid-process) for visual diagrams and interactive Q&A.
-[**Start Learning →**](docs/REFERENCE.md)
+**Start Learning →** [Reference Guide](docs/REFERENCE.md) | [Quick Overview](docs/overview/010_KEY_CONCEPTS.md)
⬆️ back to top
diff --git a/docs/REFERENCE.md b/docs/REFERENCE.md
index ebace92..bfc2344 100644
--- a/docs/REFERENCE.md
+++ b/docs/REFERENCE.md
@@ -76,6 +76,8 @@ require "solid/process"
Solid::Process supports Ruby 2.7+ and Rails 6.0+. See the [README](../README.md) for the full compatibility matrix.
+⬆️ back to top
+
---
## 2. Your First Process
@@ -165,6 +167,8 @@ result1 = Greeting.call(name: "Alice")
result2 = Greeting.call(name: "Bob")
```
+⬆️ back to top
+
---
## 3. Input Definition & Validation
@@ -292,6 +296,8 @@ class User::Registration < Solid::Process
end
```
+⬆️ back to top
+
---
## 4. Input Normalization
@@ -392,6 +398,8 @@ UserRegistration.input.normalize_value_for(:email, " FOO@BAR.COM\n")
# => "foo@bar.com"
```
+⬆️ back to top
+
---
## 5. Working with Results
@@ -490,6 +498,8 @@ end
| `Solid::Failure` | Failure results |
| `Solid::Output` | Alias for `Solid::Result` |
+⬆️ back to top
+
---
## 6. Pattern Matching
@@ -602,6 +612,8 @@ in Solid::Failure[:creation_failed, {errors:}]
end
```
+⬆️ back to top
+
---
## 7. Steps DSL
@@ -717,6 +729,8 @@ Given(a: 1, b: 2, c: 3)
This keeps your results clean, exposing only what callers need.
+⬆️ back to top
+
---
## 8. Transactions
@@ -821,6 +835,8 @@ The `.then { |result| ... }` pattern lets you wrap only part of the chain in a t
**Note:** `rollback_on_failure` requires ActiveRecord and an active database connection.
+⬆️ back to top
+
---
## 9. Dependencies
@@ -928,6 +944,8 @@ end
This allows you to swap `User::Creation` with a mock in tests.
+⬆️ back to top
+
---
## 10. Process Composition
@@ -1037,6 +1055,8 @@ def create_user_token(user:, **)
end
```
+⬆️ back to top
+
---
## 11. Callbacks
@@ -1186,6 +1206,8 @@ after_success { puts "3" } # Runs first
# Output: 3, 2, 1
```
+⬆️ back to top
+
---
## 12. Error Handling
@@ -1302,6 +1324,8 @@ end
# => Solid::Process::Error: "`Failure!()` cannot be called because the `MyProcess#output` is already set."
```
+⬆️ back to top
+
---
## 13. Instrumentation
@@ -1399,6 +1423,8 @@ cleaner.add_silencer { |line| line.include?("/gems/") }
- **Production** — Audit process executions and investigate errors
- **Performance** — See which steps execute and identify bottlenecks
+⬆️ back to top
+
---
## 14. Validators Reference
@@ -1507,6 +1533,8 @@ validates :email, email: true, allow_nil: true # Skip if nil
validates :email, email: true, allow_blank: true # Skip if blank (nil or "")
```
+⬆️ back to top
+
---
## 15. Internal Libraries
@@ -1610,6 +1638,8 @@ class User::Creation < Solid::Process
end
```
+⬆️ back to top
+
---
## 16. Testing
@@ -1827,6 +1857,8 @@ RSpec.describe User::Creation do
end
```
+⬆️ back to top
+
---
## What's Next?
@@ -1847,3 +1879,5 @@ For real-world examples, check:
- [Solid Rails App](https://github.com/solid-process/solid-rails-app) — Complete Rails application
For questions or issues, visit the [GitHub repository](https://github.com/solid-process/solid-process).
+
+⬆️ back to top