@hivehub/rulebook 5.5.2 → 5.8.0

package/templates/languages/ZIG.md

@@ -1,265 +1,265 @@
-<!-- ZIG:START -->
-# Zig Project Rules
-
-## Agent Automation Commands
-
-**CRITICAL**: Execute these commands after EVERY implementation (see AGENT_AUTOMATION module for full workflow).
-
-```bash
-# Complete quality check sequence:
-zig fmt --check .         # Format check
-zig build                 # Build verification
-zig build test            # All tests (100% pass)
-
-# No standard security audit tool for Zig yet
-```
-
-## Zig Configuration
-
-**CRITICAL**: Use Zig 0.11+ with strict compilation and comprehensive testing.
-
-- **Version**: Zig 0.11+
-- **Recommended**: Zig 0.13+
-- **Build System**: zig build (built-in)
-- **Testing**: zig test (built-in)
-- **Formatter**: zig fmt (built-in)
-
-### build.zig Requirements
-
-```zig
-const std = @import("std");
-
-pub fn build(b: *std.Build) void {
-    const target = b.standardTargetOptions(.{});
-    const optimize = b.standardOptimizeOption(.{});
-
-    // Library
-    const lib = b.addStaticLibrary(.{
-        .name = "your-lib",
-        .root_source_file = .{ .path = "src/main.zig" },
-        .target = target,
-        .optimize = optimize,
-    });
-    b.installArtifact(lib);
-
-    // Executable
-    const exe = b.addExecutable(.{
-        .name = "your-app",
-        .root_source_file = .{ .path = "src/main.zig" },
-        .target = target,
-        .optimize = optimize,
-    });
-    b.installArtifact(exe);
-
-    // Tests
-    const main_tests = b.addTest(.{
-        .root_source_file = .{ .path = "src/main.zig" },
-        .target = target,
-        .optimize = optimize,
-    });
-
-    const run_main_tests = b.addRunArtifact(main_tests);
-    const test_step = b.step("test", "Run library tests");
-    test_step.dependOn(&run_main_tests.step);
-
-    // Run command
-    const run_cmd = b.addRunArtifact(exe);
-    run_cmd.step.dependOn(b.getInstallStep());
-    if (b.args) |args| {
-        run_cmd.addArgs(args);
-    }
-
-    const run_step = b.step("run", "Run the app");
-    run_step.dependOn(&run_cmd.step);
-}
-```
-
-## Code Quality Standards
-
-### Mandatory Quality Checks
-
-**CRITICAL**: After implementing ANY feature, you MUST run these commands in order.
-
-**IMPORTANT**: These commands MUST match your GitHub Actions workflows to prevent CI/CD failures!
-
-```bash
-# Pre-Commit Checklist (MUST match .github/workflows/*.yml)
-
-# 1. Format check (matches workflow)
-zig fmt --check src/ tests/
-
-# 2. Build (MUST pass - matches workflow)
-zig build -Doptimize=ReleaseFast
-
-# 3. Build with all optimizations (matches workflow)
-zig build -Doptimize=ReleaseSmall
-zig build -Doptimize=ReleaseSafe
-
-# 4. Run all tests (MUST pass 100% - matches workflow)
-zig build test
-
-# 5. Test with different targets (matches workflow)
-zig build test -Dtarget=x86_64-linux
-zig build test -Dtarget=x86_64-windows
-zig build test -Dtarget=aarch64-macos
-
-# 6. Check for memory leaks (matches workflow)
-zig build test -Doptimize=Debug --summary all
-
-# If ANY fails: ❌ DO NOT COMMIT - Fix first!
-```
-
-**If ANY of these fail, you MUST fix the issues before committing.**
-
-**Why This Matters:**
-- Running different commands locally than in CI causes build failures
-- Zig's compile-time guarantees only work if all checks pass
-- Example: Using `zig fmt src/` locally but `zig fmt --check src/` in CI = failure
-- Example: Only testing Debug builds locally = Release builds fail in CI
-- Example: Not testing cross-compilation = deployment fails on target platform
-
-### Testing
-
-- **Framework**: Built-in `zig test`
-- **Location**: Tests can be inline or in `/tests`
-- **Coverage**: Comprehensive test coverage required
-- **Memory**: No leaks allowed (valgrind clean)
-
-Example test structure:
-```zig
-const std = @import("std");
-const testing = std.testing;
-const DataProcessor = @import("processor.zig").DataProcessor;
-
-test "DataProcessor: basic functionality" {
-    var processor = DataProcessor.init(0.5);
-    defer processor.deinit();
-    
-    const input = [_]i32{ 1, 2, 3, 4, 5 };
-    const result = try processor.process(&input);
-    defer testing.allocator.free(result);
-    
-    try testing.expect(result.len > 0);
-    try testing.expectEqual(@as(usize, 3), result.len);
-}
-
-test "DataProcessor: handles empty input" {
-    var processor = DataProcessor.init(0.5);
-    defer processor.deinit();
-    
-    const input = [_]i32{};
-    const result = try processor.process(&input);
-    defer testing.allocator.free(result);
-    
-    try testing.expectEqual(@as(usize, 0), result.len);
-}
-
-test "DataProcessor: memory management" {
-    // Test that all allocations are freed
-    const allocator = testing.allocator;
-    
-    var processor = try DataProcessor.initWithAllocator(allocator, 0.5);
-    defer processor.deinit();
-    
-    const input = try allocator.alloc(i32, 1000);
-    defer allocator.free(input);
-    
-    for (input, 0..) |*item, i| {
-        item.* = @intCast(i);
-    }
-    
-    const result = try processor.process(input);
-    defer allocator.free(result);
-    
-    // If we reach here without leaks, test passes
-    try testing.expect(result.len > 0);
-}
-```
-
-## Memory Safety
-
-**CRITICAL**: Zig provides compile-time safety - use it!
-
-```zig
-// ✅ GOOD: Safe memory management
-const std = @import("std");
-
-pub fn processData(allocator: std.mem.Allocator, input: []const i32) ![]i32 {
-    var result = std.ArrayList(i32).init(allocator);
-    defer result.deinit();  // Always cleanup!
-    
-    for (input) |value| {
-        if (value > 0) {
-            try result.append(value * 2);
-        }
-    }
-    
-    return result.toOwnedSlice();
-}
-
-// Usage with proper cleanup
-pub fn main() !void {
-    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
-    defer _ = gpa.deinit();
-    
-    const allocator = gpa.allocator();
-    
-    const input = [_]i32{ 1, 2, 3, 4, 5 };
-    const result = try processData(allocator, &input);
-    defer allocator.free(result);  // Free returned memory!
-    
-    for (result) |value| {
-        std.debug.print("{}\n", .{value});
-    }
-}
-
-// ❌ BAD: Memory leaks
-pub fn processDataLeaky(allocator: std.mem.Allocator) ![]i32 {
-    var result = std.ArrayList(i32).init(allocator);
-    // Missing defer result.deinit()!
-    
-    try result.append(42);
-    return result.toOwnedSlice();  // Leaks ArrayList memory!
-}
-```
-
-## Best Practices
-
-### DO's ✅
-
-- **USE** defer for cleanup
-- **CHECK** all error returns
-- **VALIDATE** all inputs
-- **TEST** with different allocators
-- **USE** comptime for compile-time computations
-- **PREFER** stack allocation when possible
-- **USE** tagged unions for variants
-- **CROSS-COMPILE** to verify portability
-
-### DON'Ts ❌
-
-- **NEVER** ignore error returns
-- **NEVER** use undefined behavior
-- **NEVER** leak memory
-- **NEVER** use @ptrCast without validation
-- **NEVER** assume platform specifics
-- **NEVER** skip cross-compilation tests
-- **NEVER** use global mutable state
-
-## CI/CD Requirements
-
-Must include GitHub Actions workflows:
-
-1. **Testing** (`zig-test.yml`):
-   - Test on Linux, Windows, macOS
-   - Test with Debug, ReleaseSafe, ReleaseFast, ReleaseSmall
-   - Cross-compilation tests
-   - Memory leak detection
-
-2. **Linting** (`zig-lint.yml`):
-   - zig fmt --check
-   - Build verification
-   - All optimize modes
-
-<!-- ZIG:END -->
-
+<!-- ZIG:START -->
+# Zig Project Rules
+
+## Agent Automation Commands
+
+**CRITICAL**: Execute these commands after EVERY implementation (see AGENT_AUTOMATION module for full workflow).
+
+```bash
+# Complete quality check sequence:
+zig fmt --check .         # Format check
+zig build                 # Build verification
+zig build test            # All tests (100% pass)
+
+# No standard security audit tool for Zig yet
+```
+
+## Zig Configuration
+
+**CRITICAL**: Use Zig 0.11+ with strict compilation and comprehensive testing.
+
+- **Version**: Zig 0.11+
+- **Recommended**: Zig 0.13+
+- **Build System**: zig build (built-in)
+- **Testing**: zig test (built-in)
+- **Formatter**: zig fmt (built-in)
+
+### build.zig Requirements
+
+```zig
+const std = @import("std");
+
+pub fn build(b: *std.Build) void {
+    const target = b.standardTargetOptions(.{});
+    const optimize = b.standardOptimizeOption(.{});
+
+    // Library
+    const lib = b.addStaticLibrary(.{
+        .name = "your-lib",
+        .root_source_file = .{ .path = "src/main.zig" },
+        .target = target,
+        .optimize = optimize,
+    });
+    b.installArtifact(lib);
+
+    // Executable
+    const exe = b.addExecutable(.{
+        .name = "your-app",
+        .root_source_file = .{ .path = "src/main.zig" },
+        .target = target,
+        .optimize = optimize,
+    });
+    b.installArtifact(exe);
+
+    // Tests
+    const main_tests = b.addTest(.{
+        .root_source_file = .{ .path = "src/main.zig" },
+        .target = target,
+        .optimize = optimize,
+    });
+
+    const run_main_tests = b.addRunArtifact(main_tests);
+    const test_step = b.step("test", "Run library tests");
+    test_step.dependOn(&run_main_tests.step);
+
+    // Run command
+    const run_cmd = b.addRunArtifact(exe);
+    run_cmd.step.dependOn(b.getInstallStep());
+    if (b.args) |args| {
+        run_cmd.addArgs(args);
+    }
+
+    const run_step = b.step("run", "Run the app");
+    run_step.dependOn(&run_cmd.step);
+}
+```
+
+## Code Quality Standards
+
+### Mandatory Quality Checks
+
+**CRITICAL**: After implementing ANY feature, you MUST run these commands in order.
+
+**IMPORTANT**: These commands MUST match your GitHub Actions workflows to prevent CI/CD failures!
+
+```bash
+# Pre-Commit Checklist (MUST match .github/workflows/*.yml)
+
+# 1. Format check (matches workflow)
+zig fmt --check src/ tests/
+
+# 2. Build (MUST pass - matches workflow)
+zig build -Doptimize=ReleaseFast
+
+# 3. Build with all optimizations (matches workflow)
+zig build -Doptimize=ReleaseSmall
+zig build -Doptimize=ReleaseSafe
+
+# 4. Run all tests (MUST pass 100% - matches workflow)
+zig build test
+
+# 5. Test with different targets (matches workflow)
+zig build test -Dtarget=x86_64-linux
+zig build test -Dtarget=x86_64-windows
+zig build test -Dtarget=aarch64-macos
+
+# 6. Check for memory leaks (matches workflow)
+zig build test -Doptimize=Debug --summary all
+
+# If ANY fails: ❌ DO NOT COMMIT - Fix first!
+```
+
+**If ANY of these fail, you MUST fix the issues before committing.**
+
+**Why This Matters:**
+- Running different commands locally than in CI causes build failures
+- Zig's compile-time guarantees only work if all checks pass
+- Example: Using `zig fmt src/` locally but `zig fmt --check src/` in CI = failure
+- Example: Only testing Debug builds locally = Release builds fail in CI
+- Example: Not testing cross-compilation = deployment fails on target platform
+
+### Testing
+
+- **Framework**: Built-in `zig test`
+- **Location**: Tests can be inline or in `/tests`
+- **Coverage**: Comprehensive test coverage required
+- **Memory**: No leaks allowed (valgrind clean)
+
+Example test structure:
+```zig
+const std = @import("std");
+const testing = std.testing;
+const DataProcessor = @import("processor.zig").DataProcessor;
+
+test "DataProcessor: basic functionality" {
+    var processor = DataProcessor.init(0.5);
+    defer processor.deinit();
+    
+    const input = [_]i32{ 1, 2, 3, 4, 5 };
+    const result = try processor.process(&input);
+    defer testing.allocator.free(result);
+    
+    try testing.expect(result.len > 0);
+    try testing.expectEqual(@as(usize, 3), result.len);
+}
+
+test "DataProcessor: handles empty input" {
+    var processor = DataProcessor.init(0.5);
+    defer processor.deinit();
+    
+    const input = [_]i32{};
+    const result = try processor.process(&input);
+    defer testing.allocator.free(result);
+    
+    try testing.expectEqual(@as(usize, 0), result.len);
+}
+
+test "DataProcessor: memory management" {
+    // Test that all allocations are freed
+    const allocator = testing.allocator;
+    
+    var processor = try DataProcessor.initWithAllocator(allocator, 0.5);
+    defer processor.deinit();
+    
+    const input = try allocator.alloc(i32, 1000);
+    defer allocator.free(input);
+    
+    for (input, 0..) |*item, i| {
+        item.* = @intCast(i);
+    }
+    
+    const result = try processor.process(input);
+    defer allocator.free(result);
+    
+    // If we reach here without leaks, test passes
+    try testing.expect(result.len > 0);
+}
+```
+
+## Memory Safety
+
+**CRITICAL**: Zig provides compile-time safety - use it!
+
+```zig
+// ✅ GOOD: Safe memory management
+const std = @import("std");
+
+pub fn processData(allocator: std.mem.Allocator, input: []const i32) ![]i32 {
+    var result = std.ArrayList(i32).init(allocator);
+    defer result.deinit();  // Always cleanup!
+    
+    for (input) |value| {
+        if (value > 0) {
+            try result.append(value * 2);
+        }
+    }
+    
+    return result.toOwnedSlice();
+}
+
+// Usage with proper cleanup
+pub fn main() !void {
+    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
+    defer _ = gpa.deinit();
+    
+    const allocator = gpa.allocator();
+    
+    const input = [_]i32{ 1, 2, 3, 4, 5 };
+    const result = try processData(allocator, &input);
+    defer allocator.free(result);  // Free returned memory!
+    
+    for (result) |value| {
+        std.debug.print("{}\n", .{value});
+    }
+}
+
+// ❌ BAD: Memory leaks
+pub fn processDataLeaky(allocator: std.mem.Allocator) ![]i32 {
+    var result = std.ArrayList(i32).init(allocator);
+    // Missing defer result.deinit()!
+    
+    try result.append(42);
+    return result.toOwnedSlice();  // Leaks ArrayList memory!
+}
+```
+
+## Best Practices
+
+### DO's ✅
+
+- **USE** defer for cleanup
+- **CHECK** all error returns
+- **VALIDATE** all inputs
+- **TEST** with different allocators
+- **USE** comptime for compile-time computations
+- **PREFER** stack allocation when possible
+- **USE** tagged unions for variants
+- **CROSS-COMPILE** to verify portability
+
+### DON'Ts ❌
+
+- **NEVER** ignore error returns
+- **NEVER** use undefined behavior
+- **NEVER** leak memory
+- **NEVER** use @ptrCast without validation
+- **NEVER** assume platform specifics
+- **NEVER** skip cross-compilation tests
+- **NEVER** use global mutable state
+
+## CI/CD Requirements
+
+Must include GitHub Actions workflows:
+
+1. **Testing** (`zig-test.yml`):
+   - Test on Linux, Windows, macOS
+   - Test with Debug, ReleaseSafe, ReleaseFast, ReleaseSmall
+   - Cross-compilation tests
+   - Memory leak detection
+
+2. **Linting** (`zig-lint.yml`):
+   - zig fmt --check
+   - Build verification
+   - All optimize modes
+
+<!-- ZIG:END -->
+

package/templates/libraries/go/ECHO.md

@@ -0,0 +1,18 @@
+<!-- ECHO:START -->
+# Echo Rules
+
+## Conventions
+- Create the server with `echo.New()` and configure `e.HideBanner = true` in production to suppress startup noise.
+- Register middleware with `e.Use()` globally; use `g.Use()` on route groups for middleware scoped to a subset of routes.
+- Bind and validate in one step with `c.Bind(&dto)` (calls the registered validator) or `c.Validate(&dto)` explicitly after a manual decode.
+- Implement `echo.HTTPErrorHandler` on the `Echo` instance to centralise error response formatting across all handlers.
+- Return errors from handlers rather than writing responses directly; Echo's error handler will translate `*echo.HTTPError` and custom error types for you.
+- Use `echo.WrapHandler` or `echo.WrapMiddleware` when integrating `net/http`-compatible handlers from third-party packages.
+- Set `e.Debug = true` only in development — it exposes stack traces in HTTP responses.
+
+## Avoid
+- Do not ignore the error returned by `e.Start()` or `e.StartTLS()` — wrap it in a `log.Fatal` or structured logger call.
+- Do not use `context.Context` from the standard library where `echo.Context` is available; mixing them leads to redundant value lookups.
+- Avoid defining route handlers as anonymous functions inline for anything beyond trivial cases — named functions improve stack traces and testability.
+- Do not bind request bodies in middleware; bind only inside the handler where the expected schema is known.
+<!-- ECHO:END -->

package/templates/libraries/go/GIN.md

@@ -0,0 +1,18 @@
+<!-- GIN:START -->
+# Gin Rules
+
+## Conventions
+- Use `gin.New()` instead of `gin.Default()` in production to control which middleware is loaded; add `gin.Logger()` and `gin.Recovery()` explicitly.
+- Group related routes with `r.Group("/prefix")` and attach middleware at the group level rather than the global router.
+- Bind request payloads with `c.ShouldBindJSON(&dto)` (returns error) rather than `c.BindJSON` (aborts on error) so you control the error response format.
+- Return structured errors via `c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})` — never write raw text responses for API handlers.
+- Use `c.Set` / `c.Get` for passing values through middleware; define typed keys to avoid runtime panics from untyped interface assertions.
+- Register custom validators on `binding.Validator` once at startup; do not repeat validation logic inside handlers.
+- In tests, use `httptest.NewRecorder()` with `gin.SetMode(gin.TestMode)` to avoid debug output noise.
+
+## Avoid
+- Do not store mutable state in handler closures — Gin handlers run concurrently; use the context or dependency-injected services instead.
+- Do not call `c.Abort()` without also writing a response — the client will hang waiting for a body.
+- Avoid `gin.Default()` in production; it silently adds a logger that writes to stdout and a recovery middleware you may not have configured.
+- Do not mix `c.BindJSON` and `c.ShouldBindJSON` in the same codebase — pick one convention and document it.
+<!-- GIN:END -->

package/templates/libraries/go/GORM.md

@@ -0,0 +1,18 @@
+<!-- GORM:START -->
+# GORM Rules
+
+## Conventions
+- Always check `result.Error` after every GORM call; use `errors.Is(result.Error, gorm.ErrRecordNotFound)` to distinguish not-found from other errors.
+- Open the database connection once at application startup and inject `*gorm.DB` via dependency injection — never open connections per request.
+- Use `db.WithContext(ctx)` on every query so timeouts and cancellations from the request lifecycle propagate to the database driver.
+- Prefer `db.Model(&User{}).Where(...).Updates(map[string]interface{}{...})` for partial updates — struct-based `Updates` silently skips zero values.
+- Define associations explicitly with struct tags (`gorm:"foreignKey:UserID"`) and load them deliberately with `Preload` — avoid relying on auto-preload behaviour.
+- Run `db.AutoMigrate(&Model{})` only in development or dedicated migration tooling; in production use versioned SQL migration files (e.g., golang-migrate).
+- Use `db.Transaction(func(tx *gorm.DB) error { ... })` for multi-statement operations to ensure atomicity.
+
+## Avoid
+- Do not use `db.First` without a `WHERE` clause — it silently returns the row with the lowest primary key, which is almost never correct.
+- Do not pass a pointer to a slice directly to `db.Find` without a `WHERE`; without conditions it performs a full table scan.
+- Avoid using `gorm.Model` in API response structs — it exposes `DeletedAt` and internal timestamps to callers; use a separate DTO.
+- Do not share a single `*gorm.DB` instance that has scopes or conditions already applied across goroutines — clone it with `db.Session(&gorm.Session{})` first.
+<!-- GORM:END -->

package/templates/libraries/python/DJANGO.md

@@ -0,0 +1,18 @@
+<!-- DJANGO:START -->
+# Django Rules
+
+## Conventions
+- Use class-based views (`View`, `ListView`, `DetailView`) for CRUD; function-based views only for simple one-off endpoints.
+- Define URL patterns in each app's `urls.py` and include them in the root `urls.py` via `include()`.
+- Use Django ORM querysets lazily; chain `.filter()`, `.exclude()`, `.select_related()`, `.prefetch_related()` before evaluation.
+- Keep business logic in model methods or service modules (`services.py`), not in views or templates.
+- Use `django.contrib.auth` for authentication; extend `AbstractBaseUser` or `AbstractUser` rather than a separate profile model when you need custom fields.
+- Run migrations with `makemigrations` + `migrate`; never edit migration files by hand except to squash.
+- Use `settings.py` split (`base.py` / `production.py` / `local.py`) and `django-environ` or `python-decouple` for secrets.
+
+## Avoid
+- Putting raw SQL in views — use the ORM or `Manager` custom querysets.
+- Importing settings directly in models; use `django.conf.settings` at call time, not module level.
+- Mutating `request.session` outside of view/middleware layers.
+- Using `null=True` on string-based fields (`CharField`, `TextField`) — use `blank=True` with an empty string default instead.
+<!-- DJANGO:END -->

package/templates/libraries/python/FASTAPI.md

@@ -0,0 +1,18 @@
+<!-- FASTAPI:START -->
+# FastAPI Rules
+
+## Conventions
+- Declare request bodies and responses as Pydantic models; use `response_model=` on every route to enforce output shape.
+- Use `Depends()` for dependency injection (database sessions, auth, config); keep dependencies composable and testable.
+- Organize routes in `APIRouter` instances per domain, then `app.include_router()` in `main.py` with a prefix and tags.
+- Use `async def` for I/O-bound endpoints; use `def` (sync) only for CPU-bound work that does not block the event loop.
+- Return explicit HTTP status codes via `status_code=` on the decorator or raise `HTTPException(status_code=..., detail=...)`.
+- Use `lifespan` context manager (FastAPI 0.93+) instead of deprecated `@app.on_event("startup"/"shutdown")`.
+- Enable `response_model_exclude_unset=True` on endpoints that do partial updates to avoid sending default values.
+
+## Avoid
+- Putting database calls directly in route functions — delegate to a repository or service layer.
+- Sharing a single `requests.Session` or sync client across async routes; use `httpx.AsyncClient` with `async with`.
+- Raising bare Python exceptions; always raise `HTTPException` or a custom handler registered via `app.exception_handler`.
+- Ignoring `openapi_extra` for non-standard response codes — document all 4xx/5xx you actually raise.
+<!-- FASTAPI:END -->

package/templates/libraries/python/FLASK.md

@@ -0,0 +1,17 @@
+<!-- FLASK:START -->
+# Flask Rules
+
+## Conventions
+- Use the Application Factory pattern (`create_app()`) to enable multiple app instances and clean testing.
+- Register routes via `Blueprint`s grouped by feature; import and register them in `create_app()`.
+- Use `flask.g` for request-scoped resources (e.g., DB connections); tear them down with `@app.teardown_appcontext`.
+- Access configuration from `app.config` populated via `app.config.from_object()` or environment variables; never hard-code secrets.
+- Use `flask.abort(status_code)` or return `(response, status_code)` tuples for error responses; register error handlers with `@app.errorhandler`.
+- Prefer `flask.current_app` and `flask.request` proxy objects inside request context rather than passing `app` around.
+
+## Avoid
+- Creating the `Flask` app at module level in large projects — it prevents testing with different configs.
+- Using mutable default arguments in view functions or blueprint registration.
+- Storing request-scoped state in module-level globals instead of `flask.g`.
+- Mixing `jsonify()` and raw `dict` returns inconsistently — pick one style per project.
+<!-- FLASK:END -->

package/templates/libraries/python/PYDANTIC.md

@@ -0,0 +1,17 @@
+<!-- PYDANTIC:START -->
+# Pydantic Rules
+
+## Conventions
+- Use Pydantic v2 (`BaseModel` from `pydantic`); annotate all fields with explicit Python types — avoid `Any` except at genuine boundaries.
+- Use `model_validator(mode="before")` for cross-field normalization and `field_validator` for single-field constraints.
+- Define `model_config = ConfigDict(...)` on the class instead of an inner `class Config` (v2 style).
+- Use `model.model_dump(exclude_unset=True)` for partial updates so unset fields are not sent downstream.
+- Prefer `Annotated[T, Field(...)]` for reusable constraints (min/max length, regex, ge/le) over bare `Field()` inside the model.
+- Use `RootModel[T]` for typed list/dict wrappers instead of wrapping a single field named `__root__`.
+
+## Avoid
+- Using `dict(model)` — use `model.model_dump()` to respect aliases and serialization settings.
+- Mutating model instances after creation unless `model_config = ConfigDict(frozen=False)` is intentional.
+- Relying on implicit coercion for strict domains (IDs, enums) — use `model_config = ConfigDict(strict=True)` or `StrictInt`/`StrictStr`.
+- Mixing v1 (`@validator`, inner `Config`) and v2 APIs in the same model.
+<!-- PYDANTIC:END -->