Docs: Strengthen onboarding and architecture documentation

[DerJanniku]

Goal

Improve discoverability and onboarding quality for new contributors.

Scope

• Add architecture diagram in docs
• Add API usage examples (curl + JSON)
• Add local dev troubleshooting section
• Ensure README links are complete and current

Acceptance Criteria

• New contributor can start project from docs alone
• Core docs are internally consistent
• README contains clear project status and scope