@cubis/foundry 0.3.71 → 0.3.73

package/workflows/powers/fastapi-expert/POWER.md

@@ -2,86 +2,72 @@
 ---
 inclusion: manual
 name: fastapi-expert
-description: Use when building high-performance async Python APIs with FastAPI and Pydantic V2. Invoke for async SQLAlchemy, JWT authentication, WebSockets, OpenAPI documentation.
+description: "Use when building FastAPI services with async Python, Pydantic v2, lifespan-managed resources, dependency-based auth, background task boundaries, and OpenAPI-safe request handling."
 license: MIT
 metadata:
-  author: https://github.com/Jeffallan
-  version: "1.0.0"
-  domain: backend
-  triggers: FastAPI, Pydantic, async Python, Python API, REST API Python, SQLAlchemy async, JWT authentication, OpenAPI, Swagger Python
-  role: specialist
-  scope: implementation
-  output-format: code
-  related-skills: fullstack-guardian, django-expert, test-master
+  author: cubis-foundry
+  version: "3.0"
+compatibility: Claude Code, Codex, GitHub Copilot
 ---
 
 # FastAPI Expert
 
-Senior FastAPI specialist with deep expertise in async Python, Pydantic V2, and production-grade API development.
+## Purpose
 
-## Role Definition
+Use when building FastAPI services with async Python, Pydantic v2, lifespan-managed resources, dependency-based auth, background task boundaries, and OpenAPI-safe request handling.
 
-You are a senior Python engineer with 10+ years of API development experience. You specialize in FastAPI with Pydantic V2, async SQLAlchemy, and modern Python 3.11+ patterns. You build scalable, type-safe APIs with automatic documentation.
+## When to Use
 
-## When to Use This Skill
+- Building or refactoring FastAPI REST or internal service APIs.
+- Defining Pydantic v2 models and request/response validation boundaries.
+- Designing dependency-based auth, async database access, lifespan-managed resources, and OpenAPI-safe endpoints.
+- Reviewing FastAPI code for async correctness, background task safety, and operational behavior.
 
-- Building REST APIs with FastAPI
-- Implementing Pydantic V2 validation schemas
-- Setting up async database operations
-- Implementing JWT authentication/authorization
-- Creating WebSocket endpoints
-- Optimizing API performance
+## Instructions
 
-## Core Workflow
+1. Model request, response, and error boundaries first with Pydantic v2.
+2. Decide lifespan-managed resources, dependency graph shape, and auth boundaries before adding routes.
+3. Keep async I/O explicit and do not mix sync database access into request paths.
+4. Keep routers thin, keep background work bounded, and move business rules into services or domain code.
+5. Verify OpenAPI output, auth behavior, startup or shutdown behavior, and failure paths before finishing.
 
-1. **Analyze requirements** - Identify endpoints, data models, auth needs
-2. **Design schemas** - Create Pydantic V2 models for validation
-3. **Implement** - Write async endpoints with proper dependency injection
-4. **Secure** - Add authentication, authorization, rate limiting
-5. **Test** - Write async tests with pytest and httpx
+### Baseline standards
 
-## Reference Guide
+- Use explicit type hints and Pydantic v2 patterns.
+- Keep request validation and response shaping at the boundary.
+- Use lifespan hooks for startup and teardown resources instead of ad hoc globals.
+- Prefer async database and network paths consistently.
+- Use dependency injection for shared auth/config logic.
+- Keep background tasks lightweight unless a durable queue owns the work.
+- Treat generated OpenAPI as a contract to keep clean.
 
-Load detailed guidance based on context:
+### Constraints
 
-| Topic | Reference | Load When |
-|-------|-----------|-----------|
-| Pydantic V2 | `references/pydantic-v2.md` | Creating schemas, validation, model_config |
-| SQLAlchemy | `references/async-sqlalchemy.md` | Async database, models, CRUD operations |
-| Endpoints | `references/endpoints-routing.md` | APIRouter, dependencies, routing |
-| Authentication | `references/authentication.md` | JWT, OAuth2, get_current_user |
-| Testing | `references/testing-async.md` | pytest-asyncio, httpx, fixtures |
-| Django Migration | `references/migration-from-django.md` | Migrating from Django/DRF to FastAPI |
+- Avoid mixing sync and async code casually in request handlers.
+- Avoid leaking ORM models directly as public response contracts.
+- Avoid hiding resource lifecycle in module import side effects.
+- Avoid using in-process background tasks for work that needs durable retries.
+- Avoid hiding auth or validation behavior in ad hoc helpers.
+- Avoid treating FastAPI convenience as a substitute for service boundaries.
 
-## Constraints
+## Output Format
 
-### MUST DO
-- Use type hints everywhere (FastAPI requires them)
-- Use Pydantic V2 syntax (`field_validator`, `model_validator`, `model_config`)
-- Use `Annotated` pattern for dependency injection
-- Use async/await for all I/O operations
-- Use `X | None` instead of `Optional[X]`
-- Return proper HTTP status codes
-- Document endpoints (auto-generated OpenAPI)
+Provide implementation guidance, code examples, and configuration as appropriate to the task.
 
-### MUST NOT DO
-- Use synchronous database operations
-- Skip Pydantic validation
-- Store passwords in plain text
-- Expose sensitive data in responses
-- Use Pydantic V1 syntax (`@validator`, `class Config`)
-- Mix sync and async code improperly
-- Hardcode configuration values
+## References
 
-## Output Templates
+Load on demand. Do not preload all reference files.
 
-When implementing FastAPI features, provide:
-1. Schema file (Pydantic models)
-2. Endpoint file (router with endpoints)
-3. CRUD operations if database involved
-4. Brief explanation of key decisions
+| File | Load when |
+| --- | --- |
+| `references/pydantic-async-playbook.md` | You need deeper guidance for Pydantic v2 boundaries, async correctness, lifespan resources, dependency-based auth, and OpenAPI-safe FastAPI structure. |
 
-## Knowledge Reference
+## Scripts
 
-FastAPI, Pydantic V2, async SQLAlchemy, Alembic migrations, JWT/OAuth2, pytest-asyncio, httpx, BackgroundTasks, WebSockets, dependency injection, OpenAPI/Swagger
+No helper scripts are required for this skill right now. Keep execution in `SKILL.md` and `references/` unless repeated automation becomes necessary.
+
+## Examples
+
+- "Help me with fastapi expert best practices in this project"
+- "Review my fastapi expert implementation for issues"
 ````

package/workflows/powers/fastapi-expert/SKILL.md

@@ -1,84 +1,70 @@
 ---
 name: fastapi-expert
-description: Use when building high-performance async Python APIs with FastAPI and Pydantic V2. Invoke for async SQLAlchemy, JWT authentication, WebSockets, OpenAPI documentation.
+description: "Use when building FastAPI services with async Python, Pydantic v2, lifespan-managed resources, dependency-based auth, background task boundaries, and OpenAPI-safe request handling."
 license: MIT
 metadata:
-  author: https://github.com/Jeffallan
-  version: "1.0.0"
-  domain: backend
-  triggers: FastAPI, Pydantic, async Python, Python API, REST API Python, SQLAlchemy async, JWT authentication, OpenAPI, Swagger Python
-  role: specialist
-  scope: implementation
-  output-format: code
-  related-skills: fullstack-guardian, django-expert, test-master
+  author: cubis-foundry
+  version: "3.0"
+compatibility: Claude Code, Codex, GitHub Copilot
 ---
 
 # FastAPI Expert
 
-Senior FastAPI specialist with deep expertise in async Python, Pydantic V2, and production-grade API development.
+## Purpose
 
-## Role Definition
+Use when building FastAPI services with async Python, Pydantic v2, lifespan-managed resources, dependency-based auth, background task boundaries, and OpenAPI-safe request handling.
 
-You are a senior Python engineer with 10+ years of API development experience. You specialize in FastAPI with Pydantic V2, async SQLAlchemy, and modern Python 3.11+ patterns. You build scalable, type-safe APIs with automatic documentation.
+## When to Use
 
-## When to Use This Skill
+- Building or refactoring FastAPI REST or internal service APIs.
+- Defining Pydantic v2 models and request/response validation boundaries.
+- Designing dependency-based auth, async database access, lifespan-managed resources, and OpenAPI-safe endpoints.
+- Reviewing FastAPI code for async correctness, background task safety, and operational behavior.
 
-- Building REST APIs with FastAPI
-- Implementing Pydantic V2 validation schemas
-- Setting up async database operations
-- Implementing JWT authentication/authorization
-- Creating WebSocket endpoints
-- Optimizing API performance
+## Instructions
 
-## Core Workflow
+1. Model request, response, and error boundaries first with Pydantic v2.
+2. Decide lifespan-managed resources, dependency graph shape, and auth boundaries before adding routes.
+3. Keep async I/O explicit and do not mix sync database access into request paths.
+4. Keep routers thin, keep background work bounded, and move business rules into services or domain code.
+5. Verify OpenAPI output, auth behavior, startup or shutdown behavior, and failure paths before finishing.
 
-1. **Analyze requirements** - Identify endpoints, data models, auth needs
-2. **Design schemas** - Create Pydantic V2 models for validation
-3. **Implement** - Write async endpoints with proper dependency injection
-4. **Secure** - Add authentication, authorization, rate limiting
-5. **Test** - Write async tests with pytest and httpx
+### Baseline standards
 
-## Reference Guide
+- Use explicit type hints and Pydantic v2 patterns.
+- Keep request validation and response shaping at the boundary.
+- Use lifespan hooks for startup and teardown resources instead of ad hoc globals.
+- Prefer async database and network paths consistently.
+- Use dependency injection for shared auth/config logic.
+- Keep background tasks lightweight unless a durable queue owns the work.
+- Treat generated OpenAPI as a contract to keep clean.
 
-Load detailed guidance based on context:
+### Constraints
 
-| Topic | Reference | Load When |
-|-------|-----------|-----------|
-| Pydantic V2 | `references/pydantic-v2.md` | Creating schemas, validation, model_config |
-| SQLAlchemy | `references/async-sqlalchemy.md` | Async database, models, CRUD operations |
-| Endpoints | `references/endpoints-routing.md` | APIRouter, dependencies, routing |
-| Authentication | `references/authentication.md` | JWT, OAuth2, get_current_user |
-| Testing | `references/testing-async.md` | pytest-asyncio, httpx, fixtures |
-| Django Migration | `references/migration-from-django.md` | Migrating from Django/DRF to FastAPI |
+- Avoid mixing sync and async code casually in request handlers.
+- Avoid leaking ORM models directly as public response contracts.
+- Avoid hiding resource lifecycle in module import side effects.
+- Avoid using in-process background tasks for work that needs durable retries.
+- Avoid hiding auth or validation behavior in ad hoc helpers.
+- Avoid treating FastAPI convenience as a substitute for service boundaries.
 
-## Constraints
+## Output Format
 
-### MUST DO
-- Use type hints everywhere (FastAPI requires them)
-- Use Pydantic V2 syntax (`field_validator`, `model_validator`, `model_config`)
-- Use `Annotated` pattern for dependency injection
-- Use async/await for all I/O operations
-- Use `X | None` instead of `Optional[X]`
-- Return proper HTTP status codes
-- Document endpoints (auto-generated OpenAPI)
+Provide implementation guidance, code examples, and configuration as appropriate to the task.
 
-### MUST NOT DO
-- Use synchronous database operations
-- Skip Pydantic validation
-- Store passwords in plain text
-- Expose sensitive data in responses
-- Use Pydantic V1 syntax (`@validator`, `class Config`)
-- Mix sync and async code improperly
-- Hardcode configuration values
+## References
 
-## Output Templates
+Load on demand. Do not preload all reference files.
 
-When implementing FastAPI features, provide:
-1. Schema file (Pydantic models)
-2. Endpoint file (router with endpoints)
-3. CRUD operations if database involved
-4. Brief explanation of key decisions
+| File | Load when |
+| --- | --- |
+| `references/pydantic-async-playbook.md` | You need deeper guidance for Pydantic v2 boundaries, async correctness, lifespan resources, dependency-based auth, and OpenAPI-safe FastAPI structure. |
 
-## Knowledge Reference
+## Scripts
 
-FastAPI, Pydantic V2, async SQLAlchemy, Alembic migrations, JWT/OAuth2, pytest-asyncio, httpx, BackgroundTasks, WebSockets, dependency injection, OpenAPI/Swagger
+No helper scripts are required for this skill right now. Keep execution in `SKILL.md` and `references/` unless repeated automation becomes necessary.
+
+## Examples
+
+- "Help me with fastapi expert best practices in this project"
+- "Review my fastapi expert implementation for issues"

package/workflows/powers/firebase/POWER.md

@@ -0,0 +1,65 @@
+````markdown
+---
+inclusion: manual
+name: firebase
+description: "Use when the task is specifically Firebase: Firestore or Realtime Database choice, security rules, indexes, auth, storage, cloud functions, hosting, emulator workflows, or platform-coupled rollout decisions."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "1.0"
+compatibility: Claude Code, Codex, GitHub Copilot
+---
+
+# Firebase
+
+## Purpose
+
+You are the platform specialist for Firebase application backends.
+
+Your job is to keep product-surface coupling explicit across Firestore or Realtime Database, security rules, indexes, auth, storage, functions, hosting, and emulator-driven local workflows.
+
+## When to Use
+
+- The task is specifically about Firebase or a Firebase-backed application.
+- Firestore, Realtime Database, security rules, indexes, auth, storage, functions, hosting, or emulator workflow materially changes the answer.
+- The real decision is platform coupling, local emulation, or rules-plus-index behavior.
+
+## Instructions
+
+### STANDARD OPERATING PROCEDURE (SOP)
+
+1. Confirm which Firebase products are actually in use.
+2. Separate platform decisions from generic backend or frontend code changes.
+3. Check rules, indexes, auth, and local emulator posture before changing app behavior.
+4. Keep rollout, local testing, and data-access constraints visible together.
+5. Escalate to framework or language skills only after the Firebase surface is clear.
+
+### Constraints
+
+- Do not treat Firebase as only a database choice.
+- Do not answer Firestore, rules, or auth questions as generic NoSQL advice.
+- Do not recommend platform features without checking local emulator and deployment implications.
+- Do not hide security-rule risk behind client convenience.
+
+## Output Format
+
+Provide implementation guidance, code examples, and configuration as appropriate to the task.
+
+## References
+
+Load on demand. Do not preload all reference files.
+
+| File                                        | Load when                                                                                                                     |
+| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `references/platform-routing.md`            | You need Firebase product routing across Firestore, Realtime Database, Auth, Storage, Functions, Hosting, and Emulator usage. |
+| `references/rules-and-indexes-checklist.md` | You need a sharper checklist for security rules, index requirements, auth coupling, and rollout safety.                       |
+
+## Scripts
+
+No helper scripts are required for this skill right now. Keep execution in `SKILL.md` and `references/` unless repeated automation becomes necessary.
+
+## Examples
+
+- "Help me with firebase best practices in this project"
+- "Review my firebase implementation for issues"
+````

package/workflows/powers/firebase/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: firebase
+description: "Use when the task is specifically Firebase: Firestore or Realtime Database choice, security rules, indexes, auth, storage, cloud functions, hosting, emulator workflows, or platform-coupled rollout decisions."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "1.0"
+compatibility: Claude Code, Codex, GitHub Copilot
+---
+
+# Firebase
+
+## Purpose
+
+You are the platform specialist for Firebase application backends.
+
+Your job is to keep product-surface coupling explicit across Firestore or Realtime Database, security rules, indexes, auth, storage, functions, hosting, and emulator-driven local workflows.
+
+## When to Use
+
+- The task is specifically about Firebase or a Firebase-backed application.
+- Firestore, Realtime Database, security rules, indexes, auth, storage, functions, hosting, or emulator workflow materially changes the answer.
+- The real decision is platform coupling, local emulation, or rules-plus-index behavior.
+
+## Instructions
+
+### STANDARD OPERATING PROCEDURE (SOP)
+
+1. Confirm which Firebase products are actually in use.
+2. Separate platform decisions from generic backend or frontend code changes.
+3. Check rules, indexes, auth, and local emulator posture before changing app behavior.
+4. Keep rollout, local testing, and data-access constraints visible together.
+5. Escalate to framework or language skills only after the Firebase surface is clear.
+
+### Constraints
+
+- Do not treat Firebase as only a database choice.
+- Do not answer Firestore, rules, or auth questions as generic NoSQL advice.
+- Do not recommend platform features without checking local emulator and deployment implications.
+- Do not hide security-rule risk behind client convenience.
+
+## Output Format
+
+Provide implementation guidance, code examples, and configuration as appropriate to the task.
+
+## References
+
+Load on demand. Do not preload all reference files.
+
+| File                                        | Load when                                                                                                                     |
+| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `references/platform-routing.md`            | You need Firebase product routing across Firestore, Realtime Database, Auth, Storage, Functions, Hosting, and Emulator usage. |
+| `references/rules-and-indexes-checklist.md` | You need a sharper checklist for security rules, index requirements, auth coupling, and rollout safety.                       |
+
+## Scripts
+
+No helper scripts are required for this skill right now. Keep execution in `SKILL.md` and `references/` unless repeated automation becomes necessary.
+
+## Examples
+
+- "Help me with firebase best practices in this project"
+- "Review my firebase implementation for issues"

package/workflows/powers/firebase/references/platform-routing.md

@@ -0,0 +1,16 @@
+# Firebase Platform Routing
+
+Load this when the task is Firebase-specific but the exact product surface is still unclear.
+
+## Routing
+
+- Firestore: document modeling, composite indexes, query limits, and rules coupling.
+- Realtime Database: tree shape, fan-out, listener behavior, and simpler realtime synchronization.
+- Auth: sign-in providers, session flow, user identity, and backend policy coupling.
+- Storage: object lifecycle, access rules, uploads, and media-heavy workloads.
+- Cloud Functions: backend triggers, scheduled jobs, and server-side integration points.
+- Hosting and Emulator Suite: local confidence, preview flow, and safe rollout checks.
+
+## Rule
+
+Keep Firebase product boundaries explicit. Do not answer a Firestore problem as if it were only a generic database problem.

package/workflows/powers/firebase/references/rules-and-indexes-checklist.md

@@ -0,0 +1,11 @@
+# Firebase Rules And Indexes Checklist
+
+Load this when security rules, index requirements, or rollout safety are the main risk.
+
+## Checklist
+
+- Confirm which Firebase product owns the access rule.
+- Review auth assumptions before changing client reads or writes.
+- Check whether query changes need index updates or new composite indexes.
+- Keep emulator validation in the plan before shipping rule or index changes.
+- Do not widen reads or writes without stating the blast radius.

package/workflows/powers/flutter-design-system/POWER.md

@@ -0,0 +1,63 @@
+````markdown
+---
+inclusion: manual
+name: flutter-design-system
+description: "Use when creating, auditing, or extending shared Flutter theme tokens, ThemeData, and reusable cross-feature UI primitives such as loading, error, empty, dead-letter, and sync-status components. Do not use for one-off screen styling that should remain local."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "1.0"
+compatibility: Claude Code, Codex, GitHub Copilot
+---
+
+# Flutter Design System
+
+## Purpose
+
+Keep shared Flutter visual decisions centralized in theme tokens and reusable
+UI primitives instead of repeating feature-specific styling.
+
+## When to Use
+
+- Adding or changing colors, spacing, radius, typography, or elevations
+- Wiring or refactoring app-wide `ThemeData`
+- Creating shared widgets used across multiple screens
+- Replacing hard-coded visual values with design-system tokens
+- Auditing feature UI for token compliance
+
+## Instructions
+
+1. Inspect the existing theme contract before adding new tokens.
+2. Reuse an existing token or shared widget when possible.
+3. Add a new token only when the concept is reusable across features.
+4. Keep shared widgets generic and free of feature repositories, notifiers, or routes.
+5. Prefer Material 3 theming through `ThemeData` before per-widget overrides.
+6. Replace hard-coded values in consuming widgets after updating the shared system.
+
+## Output Format
+
+Produce Flutter guidance or code that:
+
+- uses `AppColors`, `AppSpacing`, `AppTypography`, and `AppRadius` consistently,
+- keeps shared widgets generic and token-driven,
+- identifies which changes belong in theme files versus shared widgets,
+- includes audit notes when replacing hard-coded values.
+
+## References
+
+Load only what the current step needs.
+
+| File | Load when |
+| --- | --- |
+| `references/tokens-and-theme.md` | Adding tokens, changing `ThemeData`, or reviewing shared theme file organization. |
+| `references/shared-widgets.md` | Creating or auditing shared widgets such as loading, error, empty, dead-letter, or sync-status components. |
+
+## Scripts
+
+No helper scripts are required for this skill right now.
+
+## Examples
+
+- "Replace hard-coded spacing and colors in this Flutter module with shared tokens."
+- "Set up a reusable `ErrorView` and `LoadingView` for the app shell."
+````

package/workflows/powers/flutter-design-system/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: flutter-design-system
+description: "Use when creating, auditing, or extending shared Flutter theme tokens, ThemeData, and reusable cross-feature UI primitives such as loading, error, empty, dead-letter, and sync-status components. Do not use for one-off screen styling that should remain local."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "1.0"
+compatibility: Claude Code, Codex, GitHub Copilot
+---
+
+# Flutter Design System
+
+## Purpose
+
+Keep shared Flutter visual decisions centralized in theme tokens and reusable
+UI primitives instead of repeating feature-specific styling.
+
+## When to Use
+
+- Adding or changing colors, spacing, radius, typography, or elevations
+- Wiring or refactoring app-wide `ThemeData`
+- Creating shared widgets used across multiple screens
+- Replacing hard-coded visual values with design-system tokens
+- Auditing feature UI for token compliance
+
+## Instructions
+
+1. Inspect the existing theme contract before adding new tokens.
+2. Reuse an existing token or shared widget when possible.
+3. Add a new token only when the concept is reusable across features.
+4. Keep shared widgets generic and free of feature repositories, notifiers, or routes.
+5. Prefer Material 3 theming through `ThemeData` before per-widget overrides.
+6. Replace hard-coded values in consuming widgets after updating the shared system.
+
+## Output Format
+
+Produce Flutter guidance or code that:
+
+- uses `AppColors`, `AppSpacing`, `AppTypography`, and `AppRadius` consistently,
+- keeps shared widgets generic and token-driven,
+- identifies which changes belong in theme files versus shared widgets,
+- includes audit notes when replacing hard-coded values.
+
+## References
+
+Load only what the current step needs.
+
+| File | Load when |
+| --- | --- |
+| `references/tokens-and-theme.md` | Adding tokens, changing `ThemeData`, or reviewing shared theme file organization. |
+| `references/shared-widgets.md` | Creating or auditing shared widgets such as loading, error, empty, dead-letter, or sync-status components. |
+
+## Scripts
+
+No helper scripts are required for this skill right now.
+
+## Examples
+
+- "Replace hard-coded spacing and colors in this Flutter module with shared tokens."
+- "Set up a reusable `ErrorView` and `LoadingView` for the app shell."

package/workflows/powers/flutter-design-system/references/shared-widgets.md

@@ -0,0 +1,29 @@
+# Shared Widgets
+
+## Create a Shared Widget When
+
+- the widget appears in multiple features,
+- the behavior is generic,
+- the visual contract should stay consistent across the app.
+
+## Keep It Out of Shared
+
+- feature-specific business copy,
+- repository or notifier logic,
+- route-specific navigation decisions,
+- domain models that only one feature understands.
+
+## Expected Shared State Widgets
+
+- `LoadingView`: generic loading skeleton or progress state
+- `ErrorView`: user-facing error with retry affordance and visible request ID when available
+- `EmptyView`: empty-state illustration/message with optional CTA
+- `DeadLetterView`: permanent failure state for sync or outbox issues
+- `SyncStatusBadge`: normalized badge for `pendingSync`, `synced`, `failed`, `dead`, or `conflict`
+
+## Widget Contract
+
+- Accept data and callbacks through constructor parameters.
+- Use design-system tokens only.
+- Keep public APIs small and predictable.
+- Prefer composition over large configurable mega-widgets.

package/workflows/powers/flutter-design-system/references/tokens-and-theme.md

@@ -0,0 +1,34 @@
+# Tokens and Theme
+
+## Shared Theme Contract
+
+Keep app-wide visual tokens under `shared/theme/`:
+
+- `app_colors.dart`
+- `app_spacing.dart`
+- `app_radius.dart`
+- `app_typography.dart`
+- `app_theme.dart`
+
+## Token Rules
+
+- Add a token only when it represents a reusable design concept.
+- Do not add screen-specific names such as `salesCardBlue`.
+- Prefer semantic names (`success`, `warning`, `surfaceMuted`) over raw hue names when the token has product meaning.
+- Keep spacing on a small fixed scale unless the design system already supports a larger one.
+
+## ThemeData Checklist
+
+- `useMaterial3: true`
+- `colorScheme` derived from the shared token palette
+- text theme mapped from `AppTypography`
+- input, card, dialog, app bar, and button themes aligned to the same token set
+- dark theme derived intentionally instead of default inversion
+
+## Audit Checklist
+
+- No `Color(...)` literals in feature widgets unless bridging external APIs
+- No raw `EdgeInsets` numbers when a spacing token exists
+- No raw `BorderRadius.circular(...)` when a radius token exists
+- No raw `TextStyle(...)` when a typography token exists
+- Loading, error, empty, and sync-status visuals use shared widgets