@jmruthers/pace-core 0.6.9 → 0.6.11

package/docs/standards/README.md

@@ -1,203 +1,22 @@
 # Pace Standards
 
-This repository defines the **canonical development standards** for **pace-core** and **all consuming applications** in the pace-suite.
-
-These standards are **human-readable first**, but are deliberately structured so they can be **enforced by automation**, including Cursor rules, ESLint, and custom audit tooling.
-
-They are the **single source of truth**.  
-All other quality tools must align *to these standards*, not reinterpret them.
-
----
-
-## How to use these standards
-
-### pace-core
-- Treat these standards as **hard constraints**
-- pace-core sets the bar and defines the contracts
-- Any deviation must be explicitly documented here
-
-### Consuming applications
-- Inherit these standards by default
-- Only diverge where a documented exception exists
-- Consuming apps should never weaken standards silently
-
-### AI agents (Cursor, Codex, etc.)
-- Follow these standards **strictly**
-- Do **not** silence rules to "make things pass"
-- If compliance is unclear, stop and report rather than guessing
-
----
-
-## The Four Layers of Quality Enforcement
-
-The pace-suite uses **four complementary quality layers**, each with a distinct responsibility.  
-They are intentionally overlapping in *coverage*, but **not duplicative in purpose**.
-
-Think of this as *defence in depth*, not redundancy.
-
----
-
-### 1. Standards Documents (Source of Truth)
-
-**What they are**
-- Human-readable `.md` documents
-- Describe *intent*, *principles*, and *expectations*
-- Technology-agnostic where possible
-
-**What they are used for**
-- Defining *what "good" looks like*
-- Onboarding humans and AI agents
-- Resolving ambiguity when tools disagree
-- Designing new rules, lint checks, and audits
-
-**What they are NOT**
-- They are not executable
-- They do not enforce anything by themselves
-- They should not contain implementation hacks
-
-➡️ **If there is a conflict, the standards win.**
-
----
-
-### 2. Cursor Rules (Real-time Guidance)
-
-**What they are**
-- AI-optimised interpretations of the standards
-- Applied while code is being written or modified
-- Prevent mistakes *before* they land
-
-**What they are used for**
-- Steering AI agents toward correct patterns
-- Enforcing architectural intent during development
-- Reducing rework later in linting or audits
-
-**What they are NOT**
-- They are not a replacement for lint or audits
-- They should not invent new standards
-- They should not silence problems "to move on"
-
-➡️ Cursor rules **translate standards into behaviour**, but do not redefine them.
-
----
-
-### 3. ESLint (Fast, Local Static Analysis)
-
-**What it is**
-- Deterministic, file-level static analysis
-- Runs locally and in CI
-- Focused on correctness, safety, and consistency
-
-**What it is used for**
-- Catching obvious issues early (types, hooks, imports, patterns)
-- Enforcing mechanically checkable rules
-- Preventing regressions during refactors
-
-**What it is NOT**
-- ESLint should not encode complex business rules
-- It should not contain subjective or architectural debates
-- It should not be silenced to "get green builds"
-
-➡️ ESLint enforces *how code is written*, not *whether the system is correct*.
-
----
-
-### 4. Audit Tool (Deep, System-Level Analysis)
-
-**What it is**
-- A custom static analysis tool
-- Operates across files, folders, and systems
-- Understands pace-core contracts and invariants
-
-**What it is used for**
-- Validating architectural compliance (RBAC, data access, boundaries)
-- Catching issues ESLint cannot see
-- Providing actionable remediation plans
-
-**What it is NOT**
-- It is not a linter replacement
-- It should not report stylistic issues
-- It should not contradict the standards
-
-➡️ The audit tool answers: *"Is this system actually compliant?"*
-
----
-
-## How the layers work together
-
-| Layer        | Strength                         | Timing          |
-|--------------|----------------------------------|-----------------|
-| Standards    | Intent & clarity                 | Design time     |
-| Cursor rules | Preventive guidance              | Write time      |
-| ESLint       | Fast mechanical enforcement      | Dev / CI        |
-| Audit tool   | Deep architectural verification  | Review / CI     |
-
-No single layer is sufficient on its own.  
-Together, they create a **repeatable, scalable quality system** for both humans and AI.
-
----
-
-## Standards Documents
-
-The standards are organized into **10 files**, each covering a specific domain:
-
-### 0. [Standards Overview](./0-standards-overview.md)
-Entry point, precedence, how standards work, and the four layers of quality enforcement.
-
-### 1. [pace-core Compliance](./1-pace-core-compliance-standards.md)
-pace-core usage patterns, ESLint rules, secure Supabase client requirements, and compliance enforcement.
-
-### 2. [Project Structure](./2-project-structure-standards.md)
-Standard directory structure, file organization patterns, naming conventions, and migration guides.
-
-### 3. [Architecture](./3-architecture-standards.md)
-SOLID principles, component design, API design, and architectural patterns.
-
-### 4. [Code Quality](./4-code-quality-standards.md)
-TypeScript rules, naming conventions, code style patterns, and React patterns.
-
-### 5. [Styling](./5-styling-standards.md)
-**CRITICAL:** Required CSS configuration, Tailwind v4 setup, markup quality, and styling patterns.
-
-### 6. [Security & RBAC](./6-security-rbac-standards.md)
-RLS policy patterns, RBAC integration, helper functions, and security requirements.
-
-### 7. [API & Tech Stack](./7-api-tech-stack-standards.md)
-Required tech stack, API/RPC naming conventions, result shapes, and deprecation policy.
-
-### 8. [Testing & Documentation](./8-testing-documentation-standards.md)
-Testing strategy, documentation requirements, bug report templates, and feature request templates.
-
-### 9. [Operations](./9-operations-standards.md)
-Error handling patterns, performance optimization, caching strategies, and CI/CD integration.
-
----
-
-## Key Principles
-
-- **Do not silence tools** — fix the underlying issue
-- **Do not duplicate rules** — each layer has a purpose
-- **Do not diverge silently** — document exceptions explicitly
-- **Standards always win** — tools must align to them
-
----
-
-## Getting Started
-
-1. **Read the Overview** - Start with [0-standards-overview.md](./0-standards-overview.md) to understand the system
-2. **Review Critical Standards** - Pay special attention to:
-   - [5-styling-standards.md](./5-styling-standards.md) - **CRITICAL CSS configuration**
-   - [1-pace-core-compliance-standards.md](./1-pace-core-compliance-standards.md) - pace-core usage
-   - [6-security-rbac-standards.md](./6-security-rbac-standards.md) - Security and RBAC
-3. **Set Up Quality Enforcement** - Install Cursor rules and ESLint config:
-   - `npm run setup:cursor-rules` - Install Cursor rules for AI-assisted enforcement
-   - `npm run setup:eslint` - Install ESLint config for real-time linting
-4. **Run Audits** - Use the audit tool to validate compliance:
-   - `npm run audit:pace-core` - Run comprehensive audit organized by standards
-5. **Follow the Standards** - Use the standards as your guide for all development work
-6. **Reference When Needed** - Use the standards to resolve conflicts and answer questions
-
----
-
-**Last Updated:** 2025-01-28  
-**Version:** 2.0.0  
-**Applies to:** All pace-core and consuming apps
+This repository defines the **canonical development standards** for **pace-core** and **all consuming applications** in the pace-suite. They are human-readable first and enforced by Cursor rules, ESLint, and the audit tool.
+
+**Entry point:** [0-standards-overview.md](./0-standards-overview.md) — read this first for the four-layer quality system, precedence, and how to use the standards.
+
+## Standards documents (10 files)
+
+| File | Purpose |
+|------|---------|
+| [0-standards-overview.md](./0-standards-overview.md) | Entry point, four layers, precedence, file mapping |
+| [1-pace-core-compliance-standards.md](./1-pace-core-compliance-standards.md) | pace-core usage, ESLint, secure Supabase client |
+| [2-project-structure-standards.md](./2-project-structure-standards.md) | Directory structure, file organization, naming |
+| [3-architecture-standards.md](./3-architecture-standards.md) | SOLID principles, component and API design |
+| [4-code-quality-standards.md](./4-code-quality-standards.md) | TypeScript, naming, code style, React patterns |
+| [5-styling-standards.md](./5-styling-standards.md) | **CRITICAL:** CSS config, Tailwind v4, markup quality |
+| [6-security-rbac-standards.md](./6-security-rbac-standards.md) | RLS, RBAC, security requirements |
+| [7-api-tech-stack-standards.md](./7-api-tech-stack-standards.md) | Tech stack, API/RPC naming, result shapes |
+| [8-testing-documentation-standards.md](./8-testing-documentation-standards.md) | Testing strategy, documentation, templates |
+| [9-operations-standards.md](./9-operations-standards.md) | Error handling, performance, CI/CD |
+
+All other quality tools align to these standards; they are the single source of truth.

package/docs/testing/README.md

@@ -10,6 +10,14 @@ This guide covers testing strategies, patterns, and best practices for applicati
 
 > 📖 **For comprehensive testing standards and patterns**, see the [Testing Standard](../standards/testing-standard.md) - the authoritative guide for writing world-class tests in pace-core.
 
+## Quick Start
+
+**New to testing with pace-core?** Start here:
+
+1. **[Test Infrastructure Setup Guide](./test-infrastructure-setup.md)** - Complete guide to set up Vitest, coverage reporting, and test configuration in your consuming app. After following this guide, you'll be able to run `npm run test:coverage` and receive comprehensive coverage reports matching pace-core's setup.
+
+2. **This guide** - Learn testing patterns, strategies, and best practices for writing tests.
+
 ## Overview
 
 PACE Core provides comprehensive testing support with:
@@ -23,6 +31,8 @@ PACE Core provides comprehensive testing support with:
 
 ## Testing Setup
 
+> 💡 **First time setting up tests?** See the [Test Infrastructure Setup Guide](./test-infrastructure-setup.md) for complete configuration instructions.
+
 ### 1. Basic Testing Configuration
 
 ```tsx