From d4ca15b9e8e1de2eb69fd064ef6fb9bcea4c8094 Mon Sep 17 00:00:00 2001 From: Rodrigo Serradura Date: Thu, 29 Jan 2026 10:35:55 -0300 Subject: [PATCH 1/2] Add consistent navigation and separators to overview docs Add horizontal rule separators after headers and footer prev/next navigation links to all overview files for consistent navigation. Update last file's Next link to point to Reference Guide. --- docs/overview/010_KEY_CONCEPTS.md | 10 ++++++++++ docs/overview/020_BASIC_USAGE.md | 10 ++++++++++ docs/overview/030_INTERMEDIATE_USAGE.md | 10 ++++++++++ docs/overview/040_ADVANCED_USAGE.md | 10 ++++++++++ docs/overview/050_ERROR_HANDLING.md | 10 ++++++++++ docs/overview/060_TESTING.md | 10 ++++++++++ docs/overview/070_INSTRUMENTATION.md | 10 ++++++++++ docs/overview/080_RAILS_INTEGRATION.md | 10 ++++++++++ docs/overview/090_INTERNAL_LIBRARIES.md | 10 ++++++++++ docs/overview/100_PORTS_AND_ADAPTERS.md | 12 +++++++++++- 10 files changed, 101 insertions(+), 1 deletion(-) diff --git a/docs/overview/010_KEY_CONCEPTS.md b/docs/overview/010_KEY_CONCEPTS.md index 97f241d..d39ab49 100644 --- a/docs/overview/010_KEY_CONCEPTS.md +++ b/docs/overview/010_KEY_CONCEPTS.md @@ -4,6 +4,8 @@ +--- + # The Key Concepts ### What is a process? @@ -42,3 +44,11 @@ For this reason, this abstraction embraces emerging design, allowing developers Using the emerging design concept, I invite you to embrace this development cycle, write the minimum necessary to implement processes and add more solid-process features based on actual needs.

⬆️  back to top

+ +--- + + + +`Previous` [Table of Contents](../README.md#further-reading) | `Next` [Basic Usage](./020_BASIC_USAGE.md) + + diff --git a/docs/overview/020_BASIC_USAGE.md b/docs/overview/020_BASIC_USAGE.md index 76578ec..f5452df 100644 --- a/docs/overview/020_BASIC_USAGE.md +++ b/docs/overview/020_BASIC_USAGE.md @@ -4,6 +4,8 @@ +--- + # Basic Usage Every process needs an `input` block (defining attributes) and a `call` method (returning Success or Failure). @@ -60,3 +62,11 @@ For detailed explanations, examples, and advanced patterns, see: - [Your First Process](../REFERENCE.md#2-your-first-process) — step-by-step walkthrough - [Input Definition & Validation](../REFERENCE.md#3-input-definition--validation) — types, validations, and more - [Working with Results](../REFERENCE.md#5-working-with-results) — accessing values and checking status + +--- + + + +`Previous` [Key Concepts](./010_KEY_CONCEPTS.md) | `Next` [Intermediate Usage](./030_INTERMEDIATE_USAGE.md) + + diff --git a/docs/overview/030_INTERMEDIATE_USAGE.md b/docs/overview/030_INTERMEDIATE_USAGE.md index 207343e..2675d46 100644 --- a/docs/overview/030_INTERMEDIATE_USAGE.md +++ b/docs/overview/030_INTERMEDIATE_USAGE.md @@ -4,6 +4,8 @@ +--- + # Intermediate Usage The Steps DSL provides `Given`, `and_then`, `Continue`, and `and_expose` for expressing complex workflows clearly. @@ -58,3 +60,11 @@ For detailed explanations, examples, and advanced patterns, see: - [Steps DSL](../REFERENCE.md#7-steps-dsl) — complete DSL reference - [Transactions](../REFERENCE.md#8-transactions) — rollback strategies + +--- + + + +`Previous` [Basic Usage](./020_BASIC_USAGE.md) | `Next` [Advanced Usage](./040_ADVANCED_USAGE.md) + + diff --git a/docs/overview/040_ADVANCED_USAGE.md b/docs/overview/040_ADVANCED_USAGE.md index caee323..e733851 100644 --- a/docs/overview/040_ADVANCED_USAGE.md +++ b/docs/overview/040_ADVANCED_USAGE.md @@ -4,6 +4,8 @@ +--- + # Advanced Usage Use dependencies for testability, input validation for data integrity, and process composition for complex workflows. @@ -86,3 +88,11 @@ For detailed explanations, examples, and advanced patterns, see: - [Dependencies](../REFERENCE.md#9-dependencies) — injection patterns - [Process Composition](../REFERENCE.md#10-process-composition) — nesting processes - [Transactions](../REFERENCE.md#8-transactions) — rollback behavior + +--- + + + +`Previous` [Intermediate Usage](./030_INTERMEDIATE_USAGE.md) | `Next` [Error Handling](./050_ERROR_HANDLING.md) + + diff --git a/docs/overview/050_ERROR_HANDLING.md b/docs/overview/050_ERROR_HANDLING.md index 0c16b3b..316cf90 100644 --- a/docs/overview/050_ERROR_HANDLING.md +++ b/docs/overview/050_ERROR_HANDLING.md @@ -4,6 +4,8 @@ +--- + # Error Handling Handle exceptions at the class level with `rescue_from` or at the method level with inline `rescue`. @@ -87,3 +89,11 @@ end For detailed explanations, examples, and advanced patterns, see: - [Error Handling](../REFERENCE.md#12-error-handling) — complete error handling guide + +--- + + + +`Previous` [Advanced Usage](./040_ADVANCED_USAGE.md) | `Next` [Testing](./060_TESTING.md) + + diff --git a/docs/overview/060_TESTING.md b/docs/overview/060_TESTING.md index 88c755c..9424c3d 100644 --- a/docs/overview/060_TESTING.md +++ b/docs/overview/060_TESTING.md @@ -4,6 +4,8 @@ +--- + # Testing Test processes by asserting on outcomes and using dependency injection to isolate units. @@ -92,3 +94,11 @@ end For detailed explanations, examples, and advanced patterns, see: - [Testing](../REFERENCE.md#16-testing) — comprehensive testing patterns + +--- + + + +`Previous` [Error Handling](./050_ERROR_HANDLING.md) | `Next` [Instrumentation](./070_INSTRUMENTATION.md) + + diff --git a/docs/overview/070_INSTRUMENTATION.md b/docs/overview/070_INSTRUMENTATION.md index e923def..f3374a5 100644 --- a/docs/overview/070_INSTRUMENTATION.md +++ b/docs/overview/070_INSTRUMENTATION.md @@ -4,6 +4,8 @@ +--- + # Instrumentation Enable the BasicLoggerListener to observe process execution, invaluable for debugging complex flows. @@ -61,3 +63,11 @@ Backtrace: For detailed explanations, examples, and advanced patterns, see: - [Instrumentation](../REFERENCE.md#13-instrumentation) — complete logging guide + +--- + + + +`Previous` [Testing](./060_TESTING.md) | `Next` [Rails Integration](./080_RAILS_INTEGRATION.md) + + diff --git a/docs/overview/080_RAILS_INTEGRATION.md b/docs/overview/080_RAILS_INTEGRATION.md index 99d01ae..d37fc6a 100644 --- a/docs/overview/080_RAILS_INTEGRATION.md +++ b/docs/overview/080_RAILS_INTEGRATION.md @@ -4,6 +4,8 @@ +--- + # Rails Integration Solid::Process integrates naturally with Rails controllers, views, and the ActiveModel ecosystem. @@ -86,3 +88,11 @@ For detailed explanations, examples, and advanced patterns, see: - [Introduction](../REFERENCE.md#1-introduction) — installation and setup - [Pattern Matching](../REFERENCE.md#6-pattern-matching) — elegant result handling + +--- + + + +`Previous` [Instrumentation](./070_INSTRUMENTATION.md) | `Next` [Internal Libraries](./090_INTERNAL_LIBRARIES.md) + + diff --git a/docs/overview/090_INTERNAL_LIBRARIES.md b/docs/overview/090_INTERNAL_LIBRARIES.md index 9de124f..c55174d 100644 --- a/docs/overview/090_INTERNAL_LIBRARIES.md +++ b/docs/overview/090_INTERNAL_LIBRARIES.md @@ -4,6 +4,8 @@ +--- + # Internal Libraries Solid::Process includes three internal libraries you can use independently: Model, Value, and Input. @@ -95,3 +97,11 @@ end For detailed explanations, examples, and advanced patterns, see: - [Internal Libraries](../REFERENCE.md#15-internal-libraries) — complete reference + +--- + + + +`Previous` [Rails Integration](./080_RAILS_INTEGRATION.md) | `Next` [Ports and Adapters](./100_PORTS_AND_ADAPTERS.md) + + diff --git a/docs/overview/100_PORTS_AND_ADAPTERS.md b/docs/overview/100_PORTS_AND_ADAPTERS.md index f05e5e1..77457e0 100644 --- a/docs/overview/100_PORTS_AND_ADAPTERS.md +++ b/docs/overview/100_PORTS_AND_ADAPTERS.md @@ -1,9 +1,11 @@ -`Previous` [Internal Libraries](./090_INTERNAL_LIBRARIES.md) | `Next` [Table of Contents](../README.md#further-reading) +`Previous` [Internal Libraries](./090_INTERNAL_LIBRARIES.md) | `Next` [Reference Guide](../REFERENCE.md) +--- + # Ports and Adapters Use Solid::Process with hexagonal architecture to isolate business logic from external systems. @@ -80,3 +82,11 @@ For detailed explanations, examples, and advanced patterns, see: - [Dependencies](../REFERENCE.md#9-dependencies) — defining and injecting dependencies - [Process Composition](../REFERENCE.md#10-process-composition) — composing processes - [Validators Reference](../REFERENCE.md#14-validators-reference) — all built-in validators + +--- + + + +`Previous` [Internal Libraries](./090_INTERNAL_LIBRARIES.md) | `Next` [Reference Guide](../REFERENCE.md) + + From 3087dcb37ee74ba249ef21ae8c2044b890395a2f Mon Sep 17 00:00:00 2001 From: Rodrigo Serradura Date: Thu, 29 Jan 2026 10:38:56 -0300 Subject: [PATCH 2/2] Document overview file structure convention in CLAUDE.md --- .claude/CLAUDE.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index b8f4c74..02fc9b4 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -18,6 +18,24 @@ Both `README.md` and `docs/REFERENCE.md` use back-to-top navigation after each m 1. Add `

⬆️  back to top

` before the `---` that closes the section 2. Update the Table of Contents with the new entry +### Overview File Structure + +Each file in `docs/overview/` follows this layout: + +1. **Header nav** — `` block with `` `Previous` `` and `` `Next` `` links +2. **`---`** separator +3. **Content** — starts with a `#` title +4. **`---`** separator +5. **Footer nav** — `` block with the same `` `Previous` ``/`` `Next` `` links as the header + +Navigation chain: `010_KEY_CONCEPTS` → `020_BASIC_USAGE` → … → `100_PORTS_AND_ADAPTERS`. The first file's `Previous` links to `../README.md#further-reading`; the last file's `Next` links to `../REFERENCE.md`. + +When adding a new overview file: + +1. Follow the numbered naming convention (e.g., `110_NEW_TOPIC.md`) +2. Add header and footer nav blocks with `---` separators +3. Update the `Previous`/`Next` links in the adjacent files to include the new file + ## Common Commands ```bash