Overhaul README documentation

[tomas-stefano]

1. Restructure with clear Table of Contents and In Depth sections
2. Add architecture diagram and data flow diagrams
3. Add tutorial wizard with conditional branching (nationality → visa flow)
4. Document all conditional edge types (simple, conditional, multiple, custom)
5. Add In Depth sections for Repositories, Steps, Conditional Edges, Route Strategies
6. Document all repository types with examples and encryption
7. Add WizardState migration example
8. Document step attribute uniqueness requirement
9. Add Step Operators documentation with use: and add: examples
10. Add performance caveat about caching API calls in predicates
11. Update views to use GOV.UK Design System form builder
12. Add Advanced section for custom implementations

[inulty-dfe]

Good work cleaning this up 👍

I would explain what methods are available in the StateStore:

• Dynamic method look up of the current step
  - methods are called on any step (first_name is "declared" but can only be evaluated on the step that defines first_name as an attribute.
  - dynamic methods = step attributes
  - repository is available, dynamic step attributes are available, what else?

• transform_for_(read|write) on repository is key to knowing how to turn data in the system into data for the data store and vica versa. Especially as a way of dealing the step attribute uniqueness constraint (contact_email, other_email)

• I'd name this memoization rather than caching

def thing
	@thing ||= method_call
end

• Mention backlinks using @wizard.previous_step_path

[tomas-stefano]

Thanks for the feedback. All actions actioned!

[avinhurry]

README is getting a bit long (~2200 lines). It's fine for now but if it keeps expanding, it might be worth splitting into docs/.

Overall solid improvement. It's much clearer and more complete now. The tutorial flow and in depth sections will hopefully help new users a lot.