From e8df9dd442d76109dd873fd4340f4ca96dfb2963 Mon Sep 17 00:00:00 2001 From: Rodrigo Serradura Date: Thu, 29 Jan 2026 10:16:04 -0300 Subject: [PATCH 1/3] Add Quick Overview link to Start Learning section --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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

From 9d3ec34403523c825a37d9741faeca0f1f466741 Mon Sep 17 00:00:00 2001 From: Rodrigo Serradura Date: Thu, 29 Jan 2026 10:20:02 -0300 Subject: [PATCH 2/3] Add back-to-top navigation anchors to REFERENCE.md --- docs/REFERENCE.md | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) 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

From 47b4437b91881dda43a8ed2cb19bf7fedfb37f56 Mon Sep 17 00:00:00 2001 From: Rodrigo Serradura Date: Thu, 29 Jan 2026 10:22:01 -0300 Subject: [PATCH 3/3] Document back-to-top anchor convention in CLAUDE.md --- .claude/CLAUDE.md | 7 +++++++ 1 file changed, 7 insertions(+) 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