FaceSmith Automation Guide

Welcome to the FaceSmith monorepo. Please follow these conventions whenever you automate work, write prompts, or generate patches within this documentation tree and its descendants.

Workflow expectations

• Use pnpm for dependency management. Run commands from the repo root unless a package-specific command is required (then cd into that package first).
• Always run pnpm test within apps/site after modifying TypeScript, React, or safety libraries.
• Linting is handled by TypeScript and Jest in this starter; prefer type-safe changes over stylistic mass edits.
• Keep commits small, descriptive, and security-focused. Do not commit secrets, API tokens, or environment-specific artefacts.

Code style

• Favor functional, pure utilities in src/lib and re-export them through packages/core for reuse.
• Prefer TypeScript types over any. Use unknown when input sanitization is needed.
• React components should remain framework-agnostic islands: avoid Astro-specific APIs inside .tsx files.
• Keep Tailwind classes semantic and co-locate component-specific styles using utility classes instead of custom CSS when possible.

Testing guidance

• Use Testing Library for interactive components. Assert on user-visible text or ARIA roles rather than implementation details.
• Safety utilities require deterministic tests that cover both compliant and blocked prompts.

Security posture

• Maintain the Content Security Policy defined in astro.config.mjs.
• Preserve the IP-safety guardrails: never remove blocklist checks or sanitization without providing stronger alternatives.
• When integrating external AI services, route secrets through environment variables and never hard-code them in source.

Documentation

• Update docs/SECURITY.md if you change threat modeling, CSP directives, or safety logic.
• Keep README quick-start steps accurate for new contributors.

Add AI engine integration

• Edit only the Cloudflare Worker under workers/proxy and the client helper in apps/site/src/lib/generate.ts.
• Keep placeholder fallbacks so the site works without external credentials.
• Never commit real API tokens; use environment variables and Wrangler secrets for deployment.