Merge pull request #16 from solid-process/chore/references

serradura · web-flow · commit e8d58bf70db7 · 2026-01-29T10:22:19.000-03:00
Add back-to-top navigation to REFERENCE.md
diff --git 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 `<p align="right"><a href="#table-of-contents">⬆️ &nbsp;back to top</a></p>` 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
@@ -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)
 
 <p align="right"><a href="#-table-of-contents-">⬆️ &nbsp;back to top</a></p>
 
diff --git 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.
 
+<p align="right"><a href="#table-of-contents">⬆️ &nbsp;back to top</a></p>
+
 ---
 
 ## 2. Your First Process
@@ -165,6 +167,8 @@ result1 = Greeting.call(name: "Alice")
 result2 = Greeting.call(name: "Bob")
 ```
 
+<p align="right"><a href="#table-of-contents">⬆️ &nbsp;back to top</a></p>
+
 ---
 
 ## 3. Input Definition & Validation
@@ -292,6 +296,8 @@ class User::Registration < Solid::Process
 end
 ```
 
+<p align="right"><a href="#table-of-contents">⬆️ &nbsp;back to top</a></p>
+
 ---
 
 ## 4. Input Normalization
@@ -392,6 +398,8 @@ UserRegistration.input.normalize_value_for(:email, " FOO@BAR.COM\n")
 # => "foo@bar.com"
 ```
 
+<p align="right"><a href="#table-of-contents">⬆️ &nbsp;back to top</a></p>
+
 ---
 
 ## 5. Working with Results
@@ -490,6 +498,8 @@ end
 | `Solid::Failure` | Failure results |
 | `Solid::Output` | Alias for `Solid::Result` |
 
+<p align="right"><a href="#table-of-contents">⬆️ &nbsp;back to top</a></p>
+
 ---
 
 ## 6. Pattern Matching
@@ -602,6 +612,8 @@ in Solid::Failure[:creation_failed, {errors:}]
 end
 ```
 
+<p align="right"><a href="#table-of-contents">⬆️ &nbsp;back to top</a></p>
+
 ---
 
 ## 7. Steps DSL
@@ -717,6 +729,8 @@ Given(a: 1, b: 2, c: 3)
 
 This keeps your results clean, exposing only what callers need.
 
+<p align="right"><a href="#table-of-contents">⬆️ &nbsp;back to top</a></p>
+
 ---
 
 ## 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.
 
+<p align="right"><a href="#table-of-contents">⬆️ &nbsp;back to top</a></p>
+
 ---
 
 ## 9. Dependencies
@@ -928,6 +944,8 @@ end
 
 This allows you to swap `User::Creation` with a mock in tests.
 
+<p align="right"><a href="#table-of-contents">⬆️ &nbsp;back to top</a></p>
+
 ---
 
 ## 10. Process Composition
@@ -1037,6 +1055,8 @@ def create_user_token(user:, **)
 end
 ```
 
+<p align="right"><a href="#table-of-contents">⬆️ &nbsp;back to top</a></p>
+
 ---
 
 ## 11. Callbacks
@@ -1186,6 +1206,8 @@ after_success { puts "3" }  # Runs first
 # Output: 3, 2, 1
 ```
 
+<p align="right"><a href="#table-of-contents">⬆️ &nbsp;back to top</a></p>
+
 ---
 
 ## 12. Error Handling
@@ -1302,6 +1324,8 @@ end
 # => Solid::Process::Error: "`Failure!()` cannot be called because the `MyProcess#output` is already set."
 ```
 
+<p align="right"><a href="#table-of-contents">⬆️ &nbsp;back to top</a></p>
+
 ---
 
 ## 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
 
+<p align="right"><a href="#table-of-contents">⬆️ &nbsp;back to top</a></p>
+
 ---
 
 ## 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 "")
 ```
 
+<p align="right"><a href="#table-of-contents">⬆️ &nbsp;back to top</a></p>
+
 ---
 
 ## 15. Internal Libraries
@@ -1610,6 +1638,8 @@ class User::Creation < Solid::Process
 end
 ```
 
+<p align="right"><a href="#table-of-contents">⬆️ &nbsp;back to top</a></p>
+
 ---
 
 ## 16. Testing
@@ -1827,6 +1857,8 @@ RSpec.describe User::Creation do
 end
 ```
 
+<p align="right"><a href="#table-of-contents">⬆️ &nbsp;back to top</a></p>
+
 ---
 
 ## 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).
+
+<p align="right"><a href="#table-of-contents">⬆️ &nbsp;back to top</a></p>
