Modernize repository documentation for contributor and agent development

[weikanglim]

Summary

We should consider modernizing the repository’s documentation so contributors and coding agents can more easily find the right guidance and understand where new docs belong.

Example layout

• docs/concepts/ — Core mental models and glossary
• docs/guides/ — Task-oriented how-tos
• docs/reference/ — Schemas, flags, and environment variables
• docs/architecture/ — System overviews and higher-level design context

Outcomes

• Contributors and agents can quickly find the right docs
• Common tasks route to the right guidance
• Architecture context has a durable home
• The docs feel more cohesive and maintainable over time

We could also consider using docs/architecture/ for lightweight architecture decision records later if that would be helpful.

Follow-up issues

• Set up agentic workflows to keep documentation healthy #7165 Set up agentic workflows to keep documentation healthy