initial server

skills/nicegui/SKILL.md

@@ -41,9 +41,10 @@ Produce:
 1. Frame the baseline architecture.
 2. Choose optional extensions (DB, AI, docs) using decision points below.
 3. Map modules, dependencies, and key boundaries.
-4. Define key functions/classes and configuration surfaces.
-5. Produce phased checklist with rollout or migration notes when relevant.
-6. Run completion checks before returning.
+4. Define async behavior and UI responsiveness expectations.
+5. Define key functions/classes and configuration surfaces.
+6. Produce phased checklist with rollout or migration notes when relevant.
+7. Run completion checks before returning.
 
 ### 1) Baseline architecture
 
@@ -131,15 +132,27 @@ Prefer:
 
 Avoid reverse imports from services into API or UI modules.
 
-### 5) Testing minimums
+### 5) Async and UI responsiveness rules
+
+- Prefer `async def` for page handlers, service methods, and integrations when the call path includes I/O.
+- Use non-blocking clients/libraries where possible so long-running I/O does not freeze UI updates.
+- Do not run blocking calls (`time.sleep`, blocking HTTP/database clients) in UI event handlers.
+- For heavy CPU work, offload to worker/background execution and keep the UI loop free.
+- Show progress states for long actions (disable action button, show spinner/progress text, re-enable on completion).
+- Stream or chunk incremental results to the UI when workflows are multi-step or long-running.
+- Keep cancellation and timeout behavior explicit for user-triggered long tasks.
+- Ensure exceptions from async tasks are surfaced with user-friendly feedback and logged for diagnostics.
+
+### 6) Testing minimums
 
 - Test FastAPI health route behavior.
 - Test page registration wiring.
 - If DB enabled: session lifecycle and rollback behavior tests.
 - If AI enabled: graph happy path and interrupt/resume coverage.
 - If docs enabled: mounted docs route returns index page.
+- For async flows: test long-running actions preserve UI responsiveness (loading state, completion state, and error state).
 
-### 6) Styling architecture
+### 7) Styling architecture
 
 - Keep structure and layout in Python modules using NiceGUI class composition.
 - Keep visual polish in shared CSS files, loaded once at startup.
@@ -151,6 +164,7 @@ Avoid reverse imports from services into API or UI modules.
 - Pages are modularized (not single-file UI).
 - Health endpoint exists on FastAPI side.
 - Dependency direction is clean and one-way.
+- Async-first guidance is applied where I/O exists, with explicit non-blocking UX states.
 - Optional DB/AI/docs decisions are explicit and reflected in structure.
 - Output includes architecture summary and package-organized checklist.
 
@@ -171,6 +185,8 @@ Return:
 
 - Do not collapse all pages into one file.
 - Do not use globals or implicit global side effects.
+- Do not block UI event handlers with synchronous I/O or long CPU tasks.
+- Always define loading/progress/error states for long user-triggered actions.
 - Keep code minimal but production-minded.
 - Prefer clarity and maintainability over clever abstractions.