docs: add mkdocs, update links, add architecture documentation

docs/content/adr/0019-permission-dsl-format.md

@@ -0,0 +1,57 @@
+# ADR-0019: Permission DSL Format
+
+## Status
+Accepted
+
+## Context
+The platform needs a permission system that:
+- Is extensible by modules
+- Prevents typos and errors (compile-time safety)
+- Supports hierarchical permissions
+- Is easy to understand and use
+
+Permission formats considered:
+1. **String format**: `"module.resource.action"` - Simple, flexible
+2. **Enum/Constants**: Type-safe but less flexible
+3. **Hierarchical tree**: Complex but powerful
+4. **Bitmask**: Efficient but hard to read
+
+## Decision
+Use **string-based permission format** with **code-generated constants**:
+
+1. **Format**: `"{module}.{resource}.{action}"`
+   - Examples: `blog.post.create`, `user.read`, `system.health.check`
+2. **Code generation**: Generate constants from `module.yaml` files
+3. **Type safety**: `type Permission string` with generated constants
+4. **Validation**: Compile-time constants prevent typos
+
+**Rationale:**
+- Simple and readable
+- Easy to extend (modules define in manifest)
+- Code generation provides compile-time safety
+- Flexible (modules can define any format)
+- Hierarchical structure is intuitive
+- Easy to parse and match
+
+## Consequences
+
+### Positive
+- Simple and intuitive format
+- Compile-time safety via code generation
+- Easy to extend by modules
+- Human-readable
+- Flexible for various permission models
+
+### Negative
+- String comparisons (minimal performance impact)
+- Requires code generation step
+- Potential for permission string conflicts (mitigated by module prefix)
+
+### Implementation Notes
+- Define `type Permission string` in `pkg/perm/perm.go`
+- Create code generator: `scripts/generate-permissions.go`
+- Scan `modules/*/module.yaml` for permissions
+- Generate constants in `pkg/perm/generated.go`
+- Use `//go:generate` directive
+- Validate format: `^[a-z0-9]+(\.[a-z0-9]+)*$` (lowercase, dots)
+