sequenceDiagram
    participant U as User
    participant F as Frontend
    participant B as Backend
    participant A as AI Agent
    participant DB as PostgreSQL
    participant SB as Supabase

    U->>F: Request
    F->>B: API Call (JWT)
    B->>DB: Query Data
    DB-->>B: Results
    B->>A: Process with AI

    alt Streaming Mode
        A-->>F: SSE text_delta events
        F-->>U: Real-time tokens
    else Standard Mode
        A-->>B: AI Response
        B-->>F: JSON Response
        F-->>U: Rendered UI
    end

    opt Supabase configured
        B->>SB: Persist agent run
        SB-->>B: Confirmed
    end

# 1. Clone repository
git clone https://github.com/CleanExpo/NodeJS-Starter-V1.git
cd NodeJS-Starter-V1

# 2. Run automated setup
pnpm run setup              # macOS/Linux
pnpm run setup:windows      # Windows

# 3. Start development
pnpm dev

pnpm run verify

Default Login: admin@local.dev / admin123

Obsidian-style wiki-linking for O(1) discovery of agents, skills, rules, and commands.

# Regenerate indexes after adding new files
pnpm vault:index

# Check for broken wiki-links
pnpm vault:validate

# Add frontmatter to existing .md files
pnpm vault:adopt

# Full initialisation (for downstream projects)
/vault-init

Wiki-Link Syntax:

• [[skill-name]] — lookup by ID
• [[agent/frontend-specialist]] — direct path
• [[scientific-luxury#banned-elements]] — section anchor
• [[scientific-luxury|Design System]] — custom text

/vault-init           # Initialise vault system
/verify               # Run verification checks
/audit                # Framework audit
/new-feature          # Guided feature development
/minion <task>        # One-shot task execution
/skill-manager        # Analyse skill gaps

# Start all services
pnpm dev

# Run tests
pnpm turbo run test

# Type check
pnpm turbo run type-check

# Lint
pnpm turbo run lint

# Docker management
pnpm run docker:up          # Start services
pnpm run docker:down        # Stop services
pnpm run docker:reset       # Reset database

# Vault management
pnpm vault:index            # Regenerate wiki-link indexes
pnpm vault:validate         # Check for broken links

cd apps/backend

# Run server
uv run uvicorn src.api.main:app --reload

# Run tests
uv run pytest --cov

# Type check
uv run mypy src/

# Lint
uv run ruff check src/

# Unit tests
pnpm test --filter=web

# E2E tests
pnpm test:e2e --filter=web

# Type check
pnpm type-check --filter=web

# Default configuration (no changes needed)
AI_PROVIDER=ollama
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=llama3.1:8b

AI_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-xxx

All models support: SSE streaming, token counting, prompt caching, structured outputs, code execution.

Add to apps/backend/.env.local to enable advanced Anthropic API capabilities:

# Streaming (default: on)
STREAMING_ENABLED=true

# Adaptive Thinking — Opus 4.6 / Sonnet 4.6 only
THINKING_ENABLED=false
THINKING_BUDGET_TOKENS=10000

# Fast Mode — Opus 4.6 only, 2.5× faster output (research preview)
FAST_MODE_ENABLED=false

# Web Search Tool v2 — GA Feb 2026
WEB_SEARCH_ENABLED=false
WEB_SEARCH_MAX_USES=5

# Token safety guard
TOKEN_COUNT_WARNING_THRESHOLD=50000

# Agent Skills beta — Anthropic-managed Excel/Word/PDF processing
AGENT_SKILLS_ENABLED=false

# MCP Connector beta — connect remote MCP servers in the messages API
MCP_CONNECTOR_ENABLED=false

# VOICE_MODE: NOT available via Anthropic API.
# Voice is only in Claude.ai consumer app and Claude Code CLI.

See .skills/custom/anthropic-features/SKILL.md for the full capability matrix.

Without Supabase, the app uses NullStateStore — all functionality works, state is ephemeral. Add these vars to get persistent conversations, tasks, and agent_runs tables:

SUPABASE_URL=https://<project-id>.supabase.co
SUPABASE_ANON_KEY=<anon-key>
# SUPABASE_SERVICE_ROLE_KEY=<service-role-key>  # Only needed for admin ops

# Share the Supabase JWT secret so Supabase-issued user JWTs pass auth:
JWT_SECRET_KEY=<supabase-jwt-secret>

Get these from your Supabase dashboard → Settings → API.

The app automatically detects the credentials at startup and switches to SupabaseStateStore. If credentials are absent or the connection fails, it falls back to NullStateStore silently.

# Install and start Ollama
curl -fsSL https://ollama.com/install.sh | sh
ollama pull llama3.1:8b
ollama pull nomic-embed-text
ollama serve

docker compose down
docker compose up -d
docker compose logs postgres

# Check ports
lsof -i :3000   # Frontend
lsof -i :8000   # Backend
lsof -i :5432   # PostgreSQL

rm -rf node_modules apps/*/node_modules
pnpm store prune
pnpm install

All backend tests use real HS256 JWTs — the AuthMiddleware is ASGI-layer and cannot be overridden by FastAPI dependency_overrides. Tests generate tokens via:

from src.auth.jwt import create_access_token
from datetime import timedelta

AUTH_HEADERS = {
    "Authorization": f"Bearer {create_access_token({'sub': 'test@example.com'}, timedelta(hours=24))}"
}