Docs: restructure into Diataxis-style docs and align examples with current behavior

[d-lazenby]

Summary

This PR overhauls the project documentation to be clearer for end users while keeping it concise and navigable.

Closes #26

What changed

• Reworked README.md into a true landing page that delegates to focused docs.
• Added a step-by-step tutorial in TUTORIAL.md.
• Added/expanded dedicated docs for:
  • CONSUMER_SETUP.md
  • MANIFEST_SCHEMA.md
  • ARCHITECTURE.md
  • PERMISSIONS_TROUBLESHOOTING.md
• Fixed setup/example issues:
  • corrected manifest download URL in setup docs
  • corrected cron expression example
  • updated default updater reference to v1
  • corrected source_prefix examples to start with git::
• Reduced duplication between architecture and troubleshooting docs (unmanaged-module warnings now explained once, with cross-reference).
• Updated troubleshooting log guidance to match actual current runtime output.
• Standardized selector wording in docs/examples/tests:
  • exactly one of glob, file or files
  • updated in update-modules-manifest.example.yml, models.py, and test_models.py

Why

• Improve clarity and discoverability for first-time users.
• Better align docs with Diataxis principles:
  • tutorial for learning
  • how-to for setup
  • reference for schema
  • explanation for architecture
• Remove misleading or outdated examples.

Scope and impact

• No functional behavior change intended.
• Minor wording consistency change in validation/error text and corresponding test expectation.

Validation

• Updated docs reviewed for consistency and cross-linking.
• Selector wording change reflected in tests:
  • test_models.py

[ColinDaglish]

NIT: Minor formatting inconsistency

Requirement types should follow a consistent format.

At the moment, some are defined as:

`name` (required, string)

Others are defined as:

`glob` (string)

And some include defaults:

`pin` (string, default: `"sha"`)

Consider standardising all definitions to the same structure, e.g.:

`field` (required|optional, type, default: value)

This keeps things consistent across:

• required/optional
• type
• default value (where applicable)