docs(repo): document code architecture

[fdatoo]

Summary

• add package-level docs for undocumented Go packages
• add contract comments for core API/auth/eventstore/observability surfaces
• add a contributor repository architecture and layout guide, linked from the docs nav

Validation

• task fmt-check
• task lint
• go test ./internal/api/... ./internal/auth/... ./internal/automation/scene ./internal/carport/fakedriver ./internal/eventstore ./internal/observability ./internal/pkllsp ./internal/storage ./internal/starlark/... ./internal/testutil
• go test ./internal/api/... ./internal/auth/... ./internal/eventstore ./internal/observability ./internal/pkllsp ./internal/storage ./internal/web
• pre-push hook: go test ./..., go test -race ./..., go test -tags=integration ./...

Note: docs build was not run locally because zensical is not installed in this environment.