@massu/core 1.2.1 → 1.4.0-soak.0

package/commands/massu-scaffold-page.swift.md

@@ -0,0 +1,121 @@
+---
+name: massu-scaffold-page
+description: "When user wants to create a new view, screen, or page in a SwiftUI iOS / visionOS app — scaffolds the View, ViewModel, and Decodable response model with project conventions"
+allowed-tools: Bash(*), Read(*), Write(*), Edit(*), Grep(*), Glob(*)
+---
+
+# Scaffold New SwiftUI View
+
+Creates a SwiftUI View + `@MainActor` ViewModel + Decodable response model. Suitable for iOS, visionOS, or any cross-platform SwiftUI target.
+
+## What Gets Created
+
+| File | Purpose |
+|------|---------|
+| `{{paths.swift_source | default("ios/Sources")}}/Features/<feature>/Views/<Name>View.swift` | SwiftUI view |
+| `{{paths.swift_source | default("ios/Sources")}}/Features/<feature>/ViewModels/<Name>ViewModel.swift` | `@MainActor` ObservableObject |
+| `{{paths.swift_source | default("ios/Sources")}}/Features/<feature>/Models/<Name>Response.swift` | Decodable matching API contract |
+
+> **Path resolution**: substitute `{{paths.swift_source | default("ios/Sources")}}` against your project's `massu.config.yaml` (`paths.swift_source`). If unset, fall back to whatever the project already uses (`Sources/`, `apps/ios/<App>/<App>/`, etc.).
+
+## Template — `<Name>View.swift`
+
+```swift
+import SwiftUI
+
+struct <Name>View: View {
+    @StateObject private var viewModel = <Name>ViewModel()
+
+    var body: some View {
+        Group {
+            if viewModel.isLoading {
+                ProgressView()
+            } else if let error = viewModel.error {
+                ErrorState(message: error) { Task { await viewModel.load() } }
+            } else {
+                content
+            }
+        }
+        .task { await viewModel.load() }
+        .navigationTitle("<Title>")
+    }
+
+    private var content: some View {
+        // Build the real view here
+        EmptyView()
+    }
+}
+```
+
+## Template — `<Name>ViewModel.swift`
+
+```swift
+import Foundation
+
+@MainActor
+final class <Name>ViewModel: ObservableObject {
+    @Published var data: <Name>Response?
+    @Published var isLoading = false
+    @Published var error: String?
+
+    // Substitute {{detected.swift.api_client_class | default("APIClient")}} with the project's actual API wrapper.
+    private let api: {{detected.swift.api_client_class | default("APIClient")}}
+
+    init(api: {{detected.swift.api_client_class | default("APIClient")}} = .shared) {
+        self.api = api
+    }
+
+    func load() async {
+        isLoading = true
+        error = nil
+        defer { isLoading = false }
+        do {
+            data = try await api.get("/api/<endpoint>", as: <Name>Response.self)
+        } catch {
+            self.error = humanReadableError(error)
+        }
+    }
+}
+```
+
+## Template — `<Name>Response.swift`
+
+```swift
+import Foundation
+
+struct <Name>Response: Decodable {
+    // IMPORTANT: properties MUST be camelCase versions of the snake_case API keys.
+    // The decoder typically uses .convertFromSnakeCase, but mismatches decode to
+    // nil silently — verify property names against an actual API response.
+    let symbol: String
+    let priceUsd: Double         // matches "price_usd"
+    let updatedAt: Date          // matches "updated_at"
+}
+```
+
+## SwiftUI Conventions (apply in any project)
+
+- **Decodable silent nil**: with `JSONDecoder.keyDecodingStrategy = .convertFromSnakeCase`, a typo'd property decodes to nil with NO error. Hand-verify every property against a real API response — entire screens have shipped showing dead data because of this.
+- **`.system(size:weight:design:)` argument order**: weight before design. Reversed args silently fall back to default font.
+- **Biometric authentication**: for sensitive actions, use `LAPolicy.{{detected.swift.biometric_policy | default("deviceOwnerAuthenticationWithBiometrics")}}` — NOT `deviceOwnerAuthentication` (which falls back to a passcode and defeats the gate).
+- **Sheet state**: never clear `@State` sheet-bound vars in async callbacks; use `.onDismiss` instead.
+- **XcodeGen target naming**: cross-platform projects often split iOS / visionOS into separate targets (e.g., `<App>_iOS` / `<App>_visionOS`). Build the platform-specific scheme, NOT the umbrella name.
+- **`@MainActor` on view models**: any `@Published` field that drives UI must be set on the main actor. Async work updates state via `await MainActor.run { ... }` if the function isn't already main-actor-isolated.
+
+## Process
+
+1. Ask: which feature folder? Which target (iOS / visionOS / both)?
+2. Read the API endpoint's actual JSON response (e.g., `curl -sS http://<service>/api/<endpoint> | python3 -m json.tool`) — copy the EXACT key names so the Decodable can't drift.
+3. Write the three files.
+4. Add the new files to your project's manifest (`project.yml` for XcodeGen, or directly in Xcode for hand-managed projects); regen if needed: `cd {{paths.swift_source | default("ios/Sources")}}/.. && xcodegen`.
+5. Build the right scheme:
+   ```bash
+   cd {{paths.swift_source | default("ios/Sources")}}/.. && xcodebuild -scheme <Target>_iOS -destination 'generic/platform=iOS Simulator' build | tail -20
+   ```
+
+## START NOW
+
+Ask the user:
+1. Which feature folder, and which target (iOS / visionOS / both)?
+2. What does the screen show, and which API endpoint feeds it?
+3. Does it perform any sensitive action (purchase, trade, settings change)? — if yes, the project's biometric gate is required.

package/commands/massu-scaffold-router.python-django.md

@@ -0,0 +1,153 @@
+---
+name: massu-scaffold-router
+description: "Django-specific scaffold for {{paths.python_source | default("django_app")}}/views.py — creates function-based and class-based views with login_required, plus urls.py registration"
+allowed-tools: Bash(*), Read(*), Write(*), Edit(*), Grep(*), Glob(*)
+---
+
+# Scaffold New Django View
+
+Creates Django views in `{{paths.python_source | default("django_app")}}` following the project's conventions. Covers function-based views (FBV), class-based views (CBV), and the corresponding `urls.py` registration. Auth guard uses `{{detected.python.auth_dep | default("login_required")}}`.
+
+## What Gets Created
+
+| File | Purpose |
+|------|---------|
+| `{{paths.python_source | default("django_app")}}/views.py` | FBV + CBV examples |
+| `{{paths.python_source | default("django_app")}}/urls.py` | URL routing registration |
+| `{{paths.python_test | default("tests")}}/test_<name>_views.py` | View tests (auth + happy path) |
+
+> **Auth decorator**: this template uses `{{detected.python.auth_dep | default("login_required")}}` — sourced from the massu introspector. If your project uses a custom decorator or `@permission_required`, swap it in.
+
+## Template — Function-Based View
+
+```python
+"""<Name> views — describe purpose in one line."""
+
+import logging
+
+from django.contrib.auth.decorators import login_required
+from django.http import HttpRequest, JsonResponse
+from django.views.decorators.http import require_http_methods
+
+# Use the detected auth decorator if your project wraps the Django built-in.
+# from .auth import {{detected.python.auth_dep | default("login_required")}}
+
+logger = logging.getLogger(__name__)
+
+
+@{{detected.python.auth_dep | default("login_required")}}
+@require_http_methods(["GET"])
+def list_items(request: HttpRequest) -> JsonResponse:
+    """List items. Read-only — login guard is sufficient."""
+    return JsonResponse({"ok": True, "items": []})
+
+
+@{{detected.python.auth_dep | default("login_required")}}
+@require_http_methods(["POST"])
+def create_item(request: HttpRequest) -> JsonResponse:
+    """Create an item. Mutating — ensure the auth decorator enforces the right role."""
+    # Validate POST body here — never trust raw request.POST for numeric / typed fields.
+    logger.info("item created by user=%s", request.user.pk)
+    return JsonResponse({"ok": True})
+```
+
+## Template — Class-Based View
+
+```python
+from django.contrib.auth.mixins import LoginRequiredMixin
+from django.views import View
+from django.http import HttpRequest, JsonResponse
+
+
+class ItemListView(LoginRequiredMixin, View):
+    """Class-based list view. LoginRequiredMixin redirects unauthenticated users."""
+
+    def get(self, request: HttpRequest) -> JsonResponse:
+        return JsonResponse({"ok": True, "items": []})
+
+
+class ItemDetailView(LoginRequiredMixin, View):
+    def get(self, request: HttpRequest, pk: int) -> JsonResponse:
+        # Fetch from DB; raise Http404 if not found.
+        return JsonResponse({"ok": True, "id": pk})
+```
+
+## Template — `urls.py` Registration
+
+```python
+from django.urls import path
+from . import views
+
+app_name = "<name>"
+
+urlpatterns = [
+    path("items/", views.list_items, name="list"),
+    path("items/create/", views.create_item, name="create"),
+    # CBV registration:
+    path("items/<int:pk>/", views.ItemDetailView.as_view(), name="detail"),
+]
+```
+
+Then include in the project's root `urls.py`:
+
+```python
+from django.urls import path, include
+
+urlpatterns = [
+    # ...
+    path("api/<name>/", include("<app_label>.urls")),
+]
+```
+
+## Test scaffold (`{{paths.python_test | default("tests")}}/test_<name>_views.py`)
+
+```python
+import pytest
+from django.test import Client
+from django.contrib.auth import get_user_model
+
+User = get_user_model()
+
+
+@pytest.mark.django_db
+def test_list_items_requires_auth(client: Client):
+    response = client.get("/api/<name>/items/")
+    # login_required redirects; DRF returns 403 — accept either.
+    assert response.status_code in (302, 401, 403)
+
+
+@pytest.mark.django_db
+def test_list_items_authenticated(client: Client, django_user_model):
+    user = django_user_model.objects.create_user(username="tester", password="pass")
+    client.force_login(user)
+    response = client.get("/api/<name>/items/")
+    assert response.status_code == 200
+    data = response.json()
+    assert data["ok"] is True
+```
+
+## Django Conventions
+
+- **Always guard mutating views** with `{{detected.python.auth_dep | default("login_required")}}` (or a role/permission mixin for sensitive operations).
+- **Use `LoginRequiredMixin` for CBVs** — decorator-only auth on CBVs can be bypassed via HTTP method routing.
+- **Never trust `request.POST` for typed fields** — validate with a Django Form or DRF serializer.
+- **Atomic DB writes** — wrap multi-step mutations in `django.db.transaction.atomic`.
+- **CSRF** — `@require_http_methods` does NOT exempt CSRF. For JSON APIs, either use DRF's `CSRFExemptSessionAuthentication` or enforce the CSRF token client-side.
+- **Avoid N+1** — use `select_related` / `prefetch_related` in list views.
+
+## Process
+
+1. Ask user: which Django app (`app_label`)? What URL prefix? What views are needed?
+2. Confirm path: `{{paths.python_source | default("django_app")}}/views.py`.
+3. Write or append to `views.py`; write the `urls.py` snippet.
+4. Include the URL conf in the project root `urls.py`.
+5. Run migrations if the new views touch new models: `python manage.py makemigrations && python manage.py migrate`.
+6. Smoke: `python manage.py runserver` and curl or use the test client.
+
+## START NOW
+
+Ask the user:
+1. Which Django app (label) owns these views?
+2. What URL prefix? (e.g. `api/<name>/`)
+3. Function-based or class-based views (or both)?
+4. Does any view touch sensitive state? — that decides the auth decorator vs mixin.

package/commands/massu-scaffold-router.python-fastapi.md

@@ -0,0 +1,145 @@
+---
+name: massu-scaffold-router
+description: "FastAPI-specific scaffold for {{paths.python_source | default("app")}}/routers/ — creates the router file, registers it in main.py, adds Pydantic schemas, and applies the project's detected auth dependency"
+allowed-tools: Bash(*), Read(*), Write(*), Edit(*), Grep(*), Glob(*)
+---
+
+# Scaffold New FastAPI Router
+
+Creates a complete FastAPI router following the project's existing conventions in `{{paths.python_source | default("app")}}/routers/`. Auth dependency sourced from the massu introspector's `detected.python.auth_dep` (falls back to `get_current_user` if not detected).
+
+## What Gets Created
+
+| File | Purpose |
+|------|---------|
+| `{{paths.python_source | default("app")}}/routers/<name>.py` | Router with endpoints |
+| Registration in `{{paths.python_source | default("app")}}/main.py` | `app.include_router(...)` |
+| `{{paths.python_test | default("tests")}}/test_<name>_router.py` | Router test (auth + happy path + error path) |
+
+> **Auth dependency**: this template uses `{{detected.python.auth_dep | default("get_current_user")}}` — the value introspected from your codebase by massu. If your project uses a different dependency, adjust the import and `Depends(...)` call.
+
+> **Path resolution**: `paths.python_source` and `paths.python_test` come from `massu.config.yaml`. If those keys are not declared, the fallbacks `app/` and `tests/` are used.
+
+## Template
+
+```python
+"""<Name> API — describe purpose in one line.
+
+Plan: <plan-id> if applicable. Owner: <subsystem>.
+"""
+
+import logging
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+from pydantic import BaseModel, Field
+
+# Auth dependency detected from your codebase.
+from ._shared import {{detected.python.auth_dep | default("get_current_user")}}
+# from ..auth import require_role  # for endpoints that mutate sensitive state
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="{{detected.python.api_prefix_base | default("/api")}}/<name>", tags=["<name>"])
+
+
+class FooRequest(BaseModel):
+    symbol: str = Field(min_length=1, max_length=16)
+    # ALWAYS bound numeric inputs — open-ended floats are how unit-mismatch and
+    # APY-style overflow bugs sneak through.
+    quantity: float = Field(gt=0, le=1_000_000)
+
+
+class FooResponse(BaseModel):
+    ok: bool
+    payload: dict
+
+
+@router.get("/items")
+async def list_items(
+    request: Request,
+    user: dict = Depends({{detected.python.auth_dep | default("get_current_user")}}),
+) -> FooResponse:
+    """List items. Read-only — base auth dependency is sufficient."""
+    # Async-only I/O. Wrap external calls with `async with asyncio.timeout(N)`;
+    # client-library timeouts (httpx, aiohttp) alone do not cover DNS/TLS hangs.
+    return FooResponse(ok=True, payload={"items": []})
+
+
+@router.post("/orders")
+async def create_order(
+    body: FooRequest,
+    request: Request,
+    user: dict = Depends({{detected.python.auth_dep | default("get_current_user")}}),  # SWAP for require_role(...) for any state-mutating action
+) -> FooResponse:
+    """Mutating endpoint — enforce role-based auth (or service-token) here."""
+    logger.info("order created symbol=%s qty=%s user=%s", body.symbol, body.quantity, user.get("user_id"))
+    return FooResponse(ok=True, payload={"symbol": body.symbol, "qty": body.quantity})
+```
+
+## Registration in `main.py`
+
+```python
+# at top of file with other router imports
+from .routers.<name> import router as <name>_router
+
+# in the section where other routers are included
+app.include_router(<name>_router)
+```
+
+## Test scaffold (`{{paths.python_test | default("tests")}}/test_<name>_router.py`)
+
+```python
+import pytest
+from httpx import AsyncClient, ASGITransport
+
+from <project_package>.main import app  # substitute your top-level package
+
+
+@pytest.mark.asyncio
+async def test_list_items_requires_auth():
+    async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as ac:
+        r = await ac.get("{{detected.python.api_prefix_base | default("/api")}}/<name>/items")
+    assert r.status_code in (401, 403)
+
+
+@pytest.mark.asyncio
+async def test_create_order_input_validation(auth_headers):
+    async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as ac:
+        r = await ac.post("{{detected.python.api_prefix_base | default("/api")}}/<name>/orders", json={"symbol": "", "quantity": 0}, headers=auth_headers)
+    assert r.status_code == 422
+```
+
+## FastAPI Conventions (apply in any project)
+
+- **Auth choice**:
+  - `Depends({{detected.python.auth_dep | default("get_current_user")}})` for read-only endpoints
+  - A role-gated dependency (e.g. `require_role("admin")`) for ANY state-mutating endpoint — non-negotiable for safety-critical surfaces
+  - Service-token / machine-auth checks happen BEFORE any "auth disabled" dev bypass
+- **Async only**: every I/O call uses `async def` + `await`. Wrap external calls in `async with asyncio.timeout(N)` — internal client-library timeouts are not enough for DNS/TLS hangs.
+- **Bound numeric inputs**: `Field(gt=..., le=...)` on every numeric. Open-ended ranges produce overflow bugs in financial / metric / quantity contexts.
+- **Validate input strings**: symbols, IDs, slugs — use a project-local validator, never trust raw `str` for downstream lookups.
+- **No hardcoded sentinel values**: `0`, `0.00`, `""`, `None` are usually indistinguishable from real values. Be deliberate.
+- **Module-level state**: locks must be lazy (`asyncio.Lock()` at module top binds to the wrong loop). Background `create_task()` returns must be stored in a module-level set with `add_done_callback` to prevent GC.
+- **Silent drops log WARNING** — never DEBUG. Anything dropped at scale must be visible in production logs.
+- **Dependency injection**: any class that touches sensitive state (trades, memory, billing) should accept its dependencies via constructor or `set_*` — never assume singleton is pre-wired.
+
+## Process
+
+1. Ask user: what subsystem owns this router? What endpoints does it need? Which are read-only vs mutating?
+2. Confirm path: `{{paths.python_source | default("app")}}/routers/<name>.py`. If the name collides with an existing router, stop and ask.
+3. Write the router file using the template above; pick the right auth dependency per endpoint.
+4. Write the test scaffold and confirm it imports cleanly: `pytest {{paths.python_test | default("tests")}}/test_<name>_router.py -x --collect-only`.
+5. Add the `app.include_router(<name>_router)` line to `main.py` AFTER the file exists (split-commit safety).
+6. Verify route registration:
+   ```bash
+   python -c "from <project_package>.main import app; print([r.path for r in app.routes if '/api/<name>' in str(r.path)])"
+   ```
+7. Restart the service and curl-smoke the new endpoint (tests passing ≠ running process has the change).
+
+## START NOW
+
+Ask the user:
+1. What subsystem/feature owns this router?
+2. What's the URL prefix? (default: `{{detected.python.api_prefix_base | default("/api")}}/<name>`)
+3. What endpoints, and which are mutating vs read-only?
+4. Does any endpoint touch sensitive state (trades, billing, user permissions)? That decides whether to use a role-gated dependency vs the base auth dependency.

package/commands/massu-scaffold-router.python.md

@@ -0,0 +1,143 @@
+---
+name: massu-scaffold-router
+description: "When user wants to create a new FastAPI router, API endpoint, or backend procedure — scaffolds the router file, registers it in main.py, adds Pydantic schemas, applies project auth dependencies"
+allowed-tools: Bash(*), Read(*), Write(*), Edit(*), Grep(*), Glob(*)
+---
+
+# Scaffold New FastAPI Router
+
+Creates a complete FastAPI router following the project's existing conventions in `${paths.python_source}/routers/` (or wherever your project's `paths.python_source` resolves).
+
+## What Gets Created
+
+| File | Purpose |
+|------|---------|
+| `${paths.python_source}/routers/<name>.py` | Router with endpoints |
+| Registration in `${paths.python_source}/main.py` | `app.include_router(...)` |
+| `${paths.python_test}/test_<name>_router.py` | Router test (auth + happy path + error path) |
+
+> **Path resolution**: substitute the placeholders against your project's `massu.config.yaml` (`paths.python_source`, `paths.python_test`). If those keys are not declared, fall back to the conventional `app/`, `apps/<service>/<package>/`, or `src/` structure your project uses today.
+
+## Template
+
+```python
+"""<Name> API — describe purpose in one line.
+
+Plan: <plan-id> if applicable. Owner: <subsystem>.
+"""
+
+import logging
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+from pydantic import BaseModel, Field
+
+# Adjust auth import to whatever your project uses (e.g., a shared deps module).
+from ._shared import get_current_user  # rename if your project differs
+# from ..auth import require_role  # for endpoints that mutate sensitive state
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/api/<name>", tags=["<name>"])
+
+
+class FooRequest(BaseModel):
+    symbol: str = Field(min_length=1, max_length=16)
+    # ALWAYS bound numeric inputs — open-ended floats are how unit-mismatch and
+    # APY-style overflow bugs sneak through.
+    quantity: float = Field(gt=0, le=1_000_000)
+
+
+class FooResponse(BaseModel):
+    ok: bool
+    payload: dict
+
+
+@router.get("/items")
+async def list_items(
+    request: Request,
+    user: dict = Depends(get_current_user),
+) -> FooResponse:
+    """List items. Read-only — base auth dependency is sufficient."""
+    # Async-only I/O. Wrap external calls with `async with asyncio.timeout(N)`;
+    # client-library timeouts (httpx, aiohttp) alone do not cover DNS/TLS hangs.
+    return FooResponse(ok=True, payload={"items": []})
+
+
+@router.post("/orders")
+async def create_order(
+    body: FooRequest,
+    request: Request,
+    user: dict = Depends(get_current_user),  # SWAP for require_role(...) for any state-mutating action
+) -> FooResponse:
+    """Mutating endpoint — enforce role-based auth (or service-token) here."""
+    logger.info("order created symbol=%s qty=%s user=%s", body.symbol, body.quantity, user.get("user_id"))
+    return FooResponse(ok=True, payload={"symbol": body.symbol, "qty": body.quantity})
+```
+
+## Registration in `main.py`
+
+```python
+# at top of file with other router imports
+from .routers.<name> import router as <name>_router
+
+# in the section where other routers are included
+app.include_router(<name>_router)
+```
+
+## Test scaffold (`${paths.python_test}/test_<name>_router.py`)
+
+```python
+import pytest
+from httpx import AsyncClient, ASGITransport
+
+from <project_package>.main import app  # substitute your top-level package
+
+
+@pytest.mark.asyncio
+async def test_list_items_requires_auth():
+    async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as ac:
+        r = await ac.get("/api/<name>/items")
+    assert r.status_code in (401, 403)
+
+
+@pytest.mark.asyncio
+async def test_create_order_input_validation(auth_headers):
+    async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as ac:
+        r = await ac.post("/api/<name>/orders", json={"symbol": "", "quantity": 0}, headers=auth_headers)
+    assert r.status_code == 422
+```
+
+## FastAPI Conventions (apply in any project)
+
+- **Auth choice**:
+  - `Depends(get_current_user)` (or whatever your "is logged in" dep is) for read-only endpoints
+  - A role-gated dependency (e.g. `require_role("admin")`, `require_tier_or_guardian("trader")`, etc.) for ANY state-mutating endpoint — this is non-negotiable for safety-critical surfaces
+  - Service-token / machine-auth checks happen BEFORE any "auth disabled" dev bypass
+- **Async only**: every I/O call uses `async def` + `await`. Wrap external calls in `async with asyncio.timeout(N)` — internal client-library timeouts are not enough for DNS/TLS hangs.
+- **Bound numeric inputs**: `Field(gt=..., le=...)` on every numeric. Open-ended ranges produce overflow bugs in financial / metric / quantity contexts.
+- **Validate input strings**: symbols, IDs, slugs — use a project-local validator, never trust raw `str` for downstream lookups.
+- **No hardcoded sentinel values**: `0`, `0.00`, `""`, `None` are usually indistinguishable from real values. Be deliberate.
+- **Module-level state**: locks must be lazy (`asyncio.Lock()` at module top binds to the wrong loop). Background `create_task()` returns must be stored in a module-level set with `add_done_callback` to prevent GC.
+- **Silent drops log WARNING** — never DEBUG. Anything dropped at scale must be visible in production logs.
+- **Dependency injection**: any class that touches sensitive state (trades, memory, billing) should accept its dependencies via constructor or `set_*` — never assume singleton is pre-wired.
+
+## Process
+
+1. Ask user: what subsystem owns this router? What endpoints does it need? Which are read-only vs mutating?
+2. Confirm path: `${paths.python_source}/routers/<name>.py`. If the name collides with an existing router, stop and ask.
+3. Write the router file using the template above; pick the right auth dependency per endpoint.
+4. Write the test scaffold and confirm it imports cleanly: `pytest ${paths.python_test}/test_<name>_router.py -x --collect-only`.
+5. Add the `app.include_router(<name>_router)` line to `main.py` AFTER the file exists (split-commit safety).
+6. Verify route registration:
+   ```bash
+   python -c "from <project_package>.main import app; print([r.path for r in app.routes if '/api/<name>' in str(r.path)])"
+   ```
+7. Restart the service and curl-smoke the new endpoint (tests passing ≠ running process has the change). Use whatever process manager your project declares — `launchctl kickstart`, `systemctl restart`, `pm2 restart`, `docker compose up -d`, etc.
+
+## START NOW
+
+Ask the user:
+1. What subsystem/feature owns this router?
+2. What's the URL prefix? (default: `/api/<name>`)
+3. What endpoints, and which are mutating vs read-only?
+4. Does any endpoint touch sensitive state (trades, billing, user permissions)? That decides whether to use a role-gated dependency vs the base auth dependency.