Merge pull request #17 from solid-process/chore/docs-overview

serradura · web-flow · commit b71303bf01a2 · 2026-01-29T10:39:19.000-03:00
Add navigation and separators to overview docs
diff --git 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 `<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
 
+### Overview File Structure
+
+Each file in `docs/overview/` follows this layout:
+
+1. **Header nav** — `<small>` block with `` `Previous` `` and `` `Next` `` links
+2. **`---`** separator
+3. **Content** — starts with a `#` title
+4. **`---`** separator
+5. **Footer nav** — `<small>` 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
diff --git a/docs/overview/010_KEY_CONCEPTS.md b/docs/overview/010_KEY_CONCEPTS.md
@@ -4,6 +4,8 @@
 
 </small>
 
+---
+
 # 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.
 
 <p align="right"><a href="#the-key-concepts">⬆️ &nbsp;back to top</a></p>
+
+---
+
+<small>
+
+`Previous` [Table of Contents](../README.md#further-reading) | `Next` [Basic Usage](./020_BASIC_USAGE.md)
+
+</small>
diff --git a/docs/overview/020_BASIC_USAGE.md b/docs/overview/020_BASIC_USAGE.md
@@ -4,6 +4,8 @@
 
 </small>
 
+---
+
 # 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
+
+---
+
+<small>
+
+`Previous` [Key Concepts](./010_KEY_CONCEPTS.md) | `Next` [Intermediate Usage](./030_INTERMEDIATE_USAGE.md)
+
+</small>
diff --git a/docs/overview/030_INTERMEDIATE_USAGE.md b/docs/overview/030_INTERMEDIATE_USAGE.md
@@ -4,6 +4,8 @@
 
 </small>
 
+---
+
 # 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
+
+---
+
+<small>
+
+`Previous` [Basic Usage](./020_BASIC_USAGE.md) | `Next` [Advanced Usage](./040_ADVANCED_USAGE.md)
+
+</small>
diff --git a/docs/overview/040_ADVANCED_USAGE.md b/docs/overview/040_ADVANCED_USAGE.md
@@ -4,6 +4,8 @@
 
 </small>
 
+---
+
 # 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
+
+---
+
+<small>
+
+`Previous` [Intermediate Usage](./030_INTERMEDIATE_USAGE.md) | `Next` [Error Handling](./050_ERROR_HANDLING.md)
+
+</small>
diff --git a/docs/overview/050_ERROR_HANDLING.md b/docs/overview/050_ERROR_HANDLING.md
@@ -4,6 +4,8 @@
 
 </small>
 
+---
+
 # 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
+
+---
+
+<small>
+
+`Previous` [Advanced Usage](./040_ADVANCED_USAGE.md) | `Next` [Testing](./060_TESTING.md)
+
+</small>
diff --git a/docs/overview/060_TESTING.md b/docs/overview/060_TESTING.md
@@ -4,6 +4,8 @@
 
 </small>
 
+---
+
 # 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
+
+---
+
+<small>
+
+`Previous` [Error Handling](./050_ERROR_HANDLING.md) | `Next` [Instrumentation](./070_INSTRUMENTATION.md)
+
+</small>
diff --git a/docs/overview/070_INSTRUMENTATION.md b/docs/overview/070_INSTRUMENTATION.md
@@ -4,6 +4,8 @@
 
 </small>
 
+---
+
 # 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
+
+---
+
+<small>
+
+`Previous` [Testing](./060_TESTING.md) | `Next` [Rails Integration](./080_RAILS_INTEGRATION.md)
+
+</small>
diff --git a/docs/overview/080_RAILS_INTEGRATION.md b/docs/overview/080_RAILS_INTEGRATION.md
@@ -4,6 +4,8 @@
 
 </small>
 
+---
+
 # 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
+
+---
+
+<small>
+
+`Previous` [Instrumentation](./070_INSTRUMENTATION.md) | `Next` [Internal Libraries](./090_INTERNAL_LIBRARIES.md)
+
+</small>
diff --git a/docs/overview/090_INTERNAL_LIBRARIES.md b/docs/overview/090_INTERNAL_LIBRARIES.md
@@ -4,6 +4,8 @@
 
 </small>
 
+---
+
 # 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
+
+---
+
+<small>
+
+`Previous` [Rails Integration](./080_RAILS_INTEGRATION.md) | `Next` [Ports and Adapters](./100_PORTS_AND_ADAPTERS.md)
+
+</small>
diff --git a/docs/overview/100_PORTS_AND_ADAPTERS.md b/docs/overview/100_PORTS_AND_ADAPTERS.md
@@ -1,9 +1,11 @@
 <small>
 
-`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)
 
 </small>
 
+---
+
 # 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
+
+---
+
+<small>
+
+`Previous` [Internal Libraries](./090_INTERNAL_LIBRARIES.md) | `Next` [Reference Guide](../REFERENCE.md)
+
+</small>
