docs: add mkdocs, update links, add architecture documentation

docs/content/adr/0011-code-generation-tools.md

@@ -0,0 +1,53 @@
+# ADR-0011: Code Generation Tools
+
+## Status
+Accepted
+
+## Context
+The platform will use code generation for:
+- Permission constants from module manifests
+- Ent ORM code generation
+- Mock generation for testing
+- OpenAPI client/server code (future)
+
+We need to decide on tooling and workflow.
+
+## Decision
+Use **standard Go generation tools** with `go generate`:
+
+1. **Ent ORM**: `entgo.io/ent/cmd/ent` for schema code generation
+2. **Mocks**: `github.com/vektra/mockery/v2` or `github.com/golang/mock/mockgen`
+3. **Permissions**: Custom `scripts/generate-permissions.go`
+4. **OpenAPI**: `github.com/deepmap/oapi-codegen` (future)
+
+**Workflow:**
+- Use `//go:generate` directives in source files
+- Run `go generate ./...` before commits
+- Document in `Makefile` with `make generate` target
+- CI should verify generated code is up-to-date
+
+**Rationale:**
+- Standard Go tooling, well-supported
+- `go generate` is the idiomatic way to run code generation
+- Easy to integrate into CI/CD
+- Reduces manual code maintenance
+
+## Consequences
+
+### Positive
+- Automated code generation reduces errors
+- Consistent code style
+- Easy to maintain
+- Standard Go workflow
+
+### Negative
+- Requires developers to run generation before commits
+- Generated code must be committed (or verified in CI)
+- Slight learning curve for new developers
+
+### Implementation Notes
+- Add `//go:generate` directives where needed
+- Create `Makefile` target: `make generate`
+- Add CI step to verify generated code: `go generate ./... && git diff --exit-code`
+- Document in `CONTRIBUTING.md`
+