npm - cerber-core - Versions diffs - 1.1.8 → 1.1.10 - Mend

cerber-core 1.1.8 → 1.1.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (2) hide show

package/README.md +157 -1747
package/package.json +18 -19

package/README.md CHANGED Viewed

@@ -2,342 +2,151 @@
 > **AI doesn't break your project. Lack of a contract does.**
-**Cerber is a contract-driven project guardian for AI-assisted development.**
-It enforces a single source of truth (CERBER.md) across pre-commit, CI, and post-deploy health gates.
+Contract-first project guardian for AI-assisted development.
+Enforces `CERBER.md` across pre-commit, CI, and optional post-deploy gates.
 [![npm version](https://img.shields.io/npm/v/cerber-core.svg)](https://www.npmjs.com/package/cerber-core)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![GitHub](https://img.shields.io/badge/GitHub-cerber--core-blue.svg)](https://github.com/Agaslez/cerber-core)
-**Owner:** Agata Ślęzak | **Creator:** Stefan Pitek
-**Status:** Production-ready ✅
-**License:** MIT
+---
-## 🎯 Elevator Pitch
+## How to use Cerber (the intended workflow)
-Cerber is not a linter.
-It's not a CI tool.
-It's a contract that everything else must obey.
+Cerber is simple: **you write the rules once in `CERBER.md`**, Cerber enforces them forever (pre-commit + CI + optional post-deploy).
----
+**Roadmap → translated into CERBER.md contract → enforced automatically on every commit/push.**
-## 🚀 Try It Now
+### 1) Install
+```bash
+npm i -D cerber-core
+```
+### 2) Generate CERBER.md
 ```bash
-npm install cerber-core --save-dev
 npx cerber init
-# Follow prompts to generate CERBER.md contract + guardian hooks
 ```
-⭐ **Like what you see?** [Star the repo](https://github.com/Agaslez/cerber-core) and share with your team!
----
-## 🤖 For AI Agents (Copilot, Cursor, Windsurf, Claude, etc.)
-**Cerber's one rule:** `CERBER.md` is the single source of truth.
+If CERBER.md did not exist, Cerber creates a template and stops.
+Now **YOU fill the contract** (ideally with an AI assistant).
-- If `CERBER.md` is missing → generate template and **STOP**. User must fill the contract.
-- If `CERBER.md` exists → execute contract exactly as specified.
-- **Never guess architecture.** Never invent rules. Never auto-design.
+### 3) Teach Cerber using your roadmap (fastest way)
-**Schema modes:**
-- `schema.mode: template_only` → Generate minimal starter with "NOT SOURCE OF TRUTH" header
-- `schema.mode: strict` → Require existing schema file, never generate
-**Three enforcement points:**
-1. **Pre-commit** (Guardian) - Blocks violating commits
-2. **CI** (GitHub Actions) - Validates on push
-3. **Post-deploy** - Health gate checks production
-**Working with Cerber:** Read `CERBER.md` first. It tells you what's allowed and what's protected.
-### MUST (Non-Negotiable Rules for AI Agents)
-**Rule 1: Schema Generation = Translation Only**
-- Agent can **only translate** explicit rules from `CERBER.md` into `BACKEND_SCHEMA.*` format
-- If a rule is **not in CERBER.md** → ask user / fail / leave empty
-- **Never invent**, guess, or auto-generate architecture rules
-**Rule 2: NO-HEREDOC for TS/JS Files**
-- **Never** create TypeScript/JavaScript files using bash `cat <<EOF` or heredoc syntax
-- Reason: Causes `${}` template literal corruption and UTF-8 encoding issues
-- Use editor tools, `fs.writeFile`, or proper file generation utilities instead
----
+Take your project roadmap + repo structure and paste it into ChatGPT/Claude/Cursor with the **Cerber Contract Translator prompt** (see below).
-## 📊 Real Production Metrics
+Then:
+- Paste the generated contract into `CERBER.md`
+- Run init again to generate hooks/workflows/templates:
+  ```bash
+  npx cerber init
+  ```
-> From Eliksir SaaS Backend (2026-01-02 session)
-```yaml
-Time Saved: 4.5 hours in one session
-Bugs Prevented: 43 issues caught before production
-Architecture Violations: 6 caught & fixed
-Commits Blocked: 2 (saved hours of debugging)
-Production Incidents: 0 (vs 2-3/week before)
-Bug Detection Rate: 95% pre-production
-ROI: Break-even on Day 1
+### 4) Verify everything (Doctor)
+```bash
+npx cerber doctor
 ```
-**What developers say:**
+**Exit codes:**
+- `0` ✅ All checks pass
+- `2` ❌ Missing CERBER.md
+- `3` ❌ Missing schema (strict mode)
+- `4` ❌ Missing hook/workflow
-> "Guardian caught a critical auth bypass before it hit production. Saved us a potential security incident."
-> — Senior Developer, Eliksir Team
+### 5) Commit and push (Guardian + CI)
-> "Focus Mode changed how we work with AI. 500 LOC context vs 10K? Game changer."
-> — Tech Lead using TEAM layer
+- `git commit` → Guardian validates staged changes (blocks violations)
+- `git push` → GitHub Actions validates again in CI
 ---
-## 💼 Business Value
+## What Cerber enforces (in practice)
-**For CTOs & Engineering Managers:**
-- **Reduce production incidents** - 95% bugs caught pre-production (vs 60-70% manual reviews)
-- **Cut debugging costs** - 4.5 hours saved per developer per session
-- **Speed up onboarding** - CERBER.md = instant project understanding for new hires
-- **Enforce architecture** - Prevent technical debt before it enters codebase
-**Cost Comparison:**
-```
-Manual Code Reviews:     $150/hour × 2 hours/day = $300/day
-Cerber Core:             $0 (open source) + 4h one-time setup
-Break-even:              Day 1 ✅
-Ongoing savings:         $6,000/month per developer
-```
-**Who uses Cerber Core?**
-- 🏢 **Startups** - Solo founders building fast with AI (SOLO layer)
-- 👥 **Small teams** - 2-5 developers maintaining consistency (TEAM layer)
-- 🚀 **Growing companies** - Enforcing architecture as team scales
-- 🏭 **SaaS companies** - Production health monitoring (Cerber 2.1)
+- **Pre-commit (Guardian):** Blocks committing obvious violations (secrets, forbidden patterns, missing required imports, etc.)
+- **CI (GitHub Actions):** Re-validates on push/PR and protects the workflow itself (`cerber-integrity` job)
+- **Optional post-deploy:** Can validate production health if enabled in contract
 ---
-## 🎯 What is Cerber Core?
+## Cerber Contract Translator (Copy/Paste Prompt)
-**Cerber Core is a control system for Node.js architecture.**
+> Use this to generate a production-ready `CERBER.md` from your roadmap.
+> Cerber does NOT design your architecture. It enforces what you write.
-**Critical distinction:** Cerber does NOT design your system. Cerber EXECUTES your design.
+**PROMPT:**
 ```
-You decide    → CERBER.md (roadmap)
-Cerber guards → enforces your decisions
-```
+You are a "Cerber Contract Translator". Convert my roadmap + repo structure into a `CERBER.md` contract.
-### 💎 The Core Value: Your Roadmap Becomes Executable Law
+RULES:
+- Do NOT invent architecture or rules.
+- Only translate what I explicitly provide.
+- If something is missing, ask up to 10 questions in a `QUESTIONS` section and leave placeholders.
+- Output must be a complete `CERBER.md` with:
+  1) CERBER_CONTRACT (YAML)
+  2) ROADMAP_AS_LAW (milestones)
+  3) AI_AGENT_RULES (no guessing)
+  4) PROTECTED_ASSETS
+  5) CERBER_OVERRIDE (TTL safety fuse)
+  6) QUESTIONS
-**Traditional problem:**
-- Architect designs system → creates documentation
-- Developers code → slowly drift from the plan
-- Architecture reviews catch violations **too late**
-- Technical debt accumulates
-- **You pay for architecture again and again**
-**Cerber Core solution:**
-```
-✅ Architect defines rules once (CERBER.md contract)
-✅ Cerber enforces automatically forever
-✅ Every commit validates against your roadmap (<1 second)
-✅ Architecture stays intact as team scales
-```
+INPUT I PROVIDE:
+- Roadmap (what we are building, milestones, priorities)
+- Repo structure (`tree -L 3` or folder list)
+- Tech stack + commands for smoke/e2e/build
+- Integrations (Stripe/Ghost/Cloudinary/etc.)
+- What files/paths are "protected" from deletion
-**💰 Pay your architect once. Cerber guards the plan.**
-Instead of hoping developers "follow the docs" → **Guardian blocks commits that violate your architecture**
-```typescript
-// Your roadmap becomes code:
-export const BACKEND_SCHEMA = {
-  rules: [
-    {
-      name: 'Protected routes must use authenticateToken',
-      pattern: /routes\/.*\.ts$/,
-      requiredImports: ['authenticateToken'],
-      severity: 'error'  // Blocks violating commits
-    }
-  ]
-};
+Now generate `CERBER.md`.
 ```
-**Result:** $6,000/month saved per developer. Architecture that doesn't erode. Teams that scale without chaos.
-**Four Layers:**
-1. **🛡️ Guardian 1.0** - Pre-commit architecture validator
-   - Schema-as-Code (self-documenting architecture rules)
-   - Architect approval system for justified exceptions
-   - Forbidden pattern detection with exceptions
-   - Fast feedback (<1 second validation)
-2. **🔍 Cerber 2.1** - Runtime health diagnostics
-   - Deployment quality gates
-   - Detailed diagnostics (diagnosis + rootCause + fix)
-   - Severity levels (critical/error/warning)
-   - Automatic rollback on critical issues
-3. **⚡ SOLO** - Automation for solo developers
-   - Auto-repair (format, sync, changelog)
-   - Dependency health checks
-   - Performance budget enforcement
-   - Daily snapshots & dashboard
-4. **👥 TEAM** - Collaboration tools for teams
-   - **Focus Mode** - Generate 500 LOC context (vs 10K LOC) ⭐
-   - Module boundaries enforcement
-   - Connection contracts between modules
-   - CERBER.md project mapping
----
-## 🤔 Why Cerber Exists
-AI tools don't understand your project boundaries.
-They generate changes that cause:
-- **Schema drift** - Models diverge from database reality
-- **Architecture violations** - Security patterns bypassed
-- **CI fail loops** - 2-3 hours wasted on fixes
-- **Deployments without health validation** - Production incidents
-**Cerber fixes this by enforcing a human-written contract:**
-**CERBER.md is the only source of truth.**
 ---
-## 🔥 How Cerber is Different
+## For AI Agents (Copilot / Cursor / Windsurf / Claude / etc.)
-**Husky** runs scripts.
-**Linters** check syntax.
-**CI** runs pipelines.
+**Single rule:** `CERBER.md` is the ONLY source of truth.
-**Cerber enforces project intent.**
+### Agent must follow this protocol
-Cerber does not guess.
-Cerber does not invent rules.
-Cerber executes your contract.
+1) **If `CERBER.md` is missing:**
+   - Run `npx cerber init` to generate template
+   - STOP (user must provide contract content)
----
+2) **If `CERBER.md` exists:**
+   - Read it first
+   - Execute exactly what it says
+   - Do NOT invent rules, do NOT infer architecture
-## ✅ When to Use Cerber
+3) **Schema policy (important):**
+   - If `schema.mode: strict` → DO NOT generate schema files
+   - If `schema.mode: template_only` → you may generate only the minimal template (NOT decisions)
-**Use Cerber if:**
-- ✅ You work with AI coding assistants / agents
-- ✅ Your project has strict architecture or schema rules
-- ✅ CI failures waste time
-- ✅ You need a single source of truth for humans + AI
+4) **Safety rules:**
+   - Never disable or rename CI job id: `cerber-ci`
+   - Never remove: `CERBER.md`, `.github/workflows/cerber.yml`, `scripts/cerber-guardian.mjs`, `.husky/pre-commit`, `.github/CODEOWNERS`
+   - Never bypass checks using `continue-on-error`
+   - Never use `cat <<EOF` for TS/JS (corrupts `${}` template literals)
-**Do NOT use Cerber if:**
-- ❌ You want the tool to design your architecture
-- ❌ You don't want to maintain a contract (CERBER.md)
+**If a required rule is not present in `CERBER.md` → ASK USER or FAIL FAST.**
 ---
-## 🎯 ONE SOURCE OF TRUTH
-**Critical principle:** Cerber does NOT design your system. Cerber enforces YOUR design.
-### The Rule
-```
-📜 CERBER.md = Your roadmap (single source of truth)
-🛡️ Guardian = Enforces CERBER.md rules
-📋 Schema files = Optional mirrors of CERBER.md (NOT source of truth)
-```
-**What this means:**
-✅ **CERBER.md defines everything** - architecture, rules, team mode
-✅ **Cerber executes CERBER.md** - no assumptions, no magic
-✅ **Schema files are user-owned** - Cerber helps, never decides
-✅ **You design. Cerber guards.** - separation of concerns
-❌ **Cerber does NOT guess your architecture**
-❌ **Cerber does NOT infer folder structures**
-❌ **Cerber does NOT auto-design systems**
-### Schema Mode: Strict vs Template_Only
-In `CERBER.md` contract, you control schema generation:
-```yaml
-schema:
-  enabled: true
-  file: BACKEND_SCHEMA.mjs
-  mode: strict  # or template_only
-```
-**For mature teams → `mode: strict`**
-- ✅ Cerber NEVER creates schema file
-- ✅ You create schema based on YOUR architecture
-- ✅ Full control, no helpers, no assumptions
-- ✅ `npx cerber init` shows: "You must create BACKEND_SCHEMA.mjs"
-**For beginners → `mode: template_only`**
-- ✅ Cerber creates minimal template if file missing
-- ⚠️ Template says: "NOT SOURCE OF TRUTH - Edit to match CERBER.md"
-- ✅ Empty structures, commented examples only
-- ✅ Helper scaffold, NOT design decision
-**Default:** `template_only` (backward compatible)
+## 🔗 Links
-**Philosophy:**
-```
-Traditional tools:
-  → Auto-generate everything
-  → Assume folder structures
-  → "Helpful" magic that creates chaos
-Cerber Core:
-  → Execute CERBER.md contract
-  → Never assume architecture
-  → One decision point (CERBER.md)
-  → Works WITH AI agents, not against them
-```
-**Why this matters:**
-When your team (or AI agents) follow ONE source of truth:
-- ✅ No conflicts between "docs" and "reality"
-- ✅ No drift between "schema" and "roadmap"
-- ✅ Clear authority: CERBER.md decides, Cerber enforces
-- ✅ Architecture stays intact as team/AI scales
-**This is not "another tool". This is a control system.**
+- **Repository:** https://github.com/Agaslez/cerber-core
+- **Releases:** https://github.com/Agaslez/cerber-core/releases
+- **Security Policy:** https://github.com/Agaslez/cerber-core/blob/main/SECURITY.md
+- **Discussions:** https://github.com/Agaslez/cerber-core/discussions
+- **Full Documentation:** [docs/README_LONG.md](docs/README_LONG.md)
 ---
-## 🚀 Quick Start
-### 30-Second Setup ⚡ (New in v1.1.0!)
-```bash
-npm install cerber-core --save-dev
-npx cerber init
-```
-**How it works:**
-**If CERBER.md is missing** → Cerber creates a template and exits.
-1. Fill the contract (`CERBER_CONTRACT`) with your project settings
-2. Choose mode: `solo` | `dev` | `team`
-3. Enable features: `guardian`, `health`, `ci`
-**Run `npx cerber init` again** to generate:
-- ✅ **Guardian hook + runner** - Pre-commit validation
-- ✅ **Health templates** - Production monitoring endpoints
-- ✅ **GitHub Actions workflow** - CI/CD with stable check names
-- ✅ **Team mode: CODEOWNERS** - Schema ownership enforcement
-**Example CERBER.md:**
+## 📋 Minimal CERBER.md Example
 ```yaml
 ## CERBER_CONTRACT
-\`\`\`yaml
+\```yaml
 version: 1
-mode: dev  # solo | dev | team
+mode: solo  # solo | dev | team
 guardian:
   enabled: true
@@ -346,9 +155,7 @@ guardian:
 schema:
   enabled: true
   file: BACKEND_SCHEMA.mjs
-  mode: template_only  # strict (mature teams) | template_only (beginners)
-  # strict = You create schema, Cerber never generates
-  # template_only = Cerber creates minimal helper if missing
+  mode: strict  # Recommended: You create schema, Cerber never generates
 health:
   enabled: true
@@ -357,1272 +164,97 @@ health:
 ci:
   provider: github
   branches: [main]
-  requiredOnPR: true
-\`\`\`
-```
-**Error handling:**
-If CERBER.md exists but is invalid → you'll get a **clear error message** with:
-- Exact problem location
-- Expected format
-- Suggestion: `npx cerber init --print-template` to see valid example
-**Useful flags:**
-```bash
-npx cerber init --dry-run       # Preview without creating files
-npx cerber init --force          # Overwrite existing files
-npx cerber init --print-template # Print template to stdout
-```
-**What happens:**
-- ✅ Creates `CERBER.md` with your architecture contract
-- ✅ Generates Guardian pre-commit hooks
-- ✅ Sets up health check templates
-- ✅ Configures GitHub Actions workflow
-- ✅ Adapts to your mode: solo/dev/team
-**Next step:** Just commit! Guardian now protects your architecture.
----
-### Manual Setup (Alternative)
-If you prefer manual configuration, follow the guides below.
-### Installation
-```bash
-npm install cerber-core --save-dev
-```
-### Choose Your Path
-> ⚠️ **Note:** Examples below show common patterns. Copy and **customize to YOUR architecture**. Schema files are templates, not decisions.
-#### 🎨 **Frontend Developer (React/Vue/Angular)**
-```bash
-# 1. Initialize Cerber (generates CERBER.md + templates)
-npx cerber init --mode=solo
-# 2. Customize your schema for frontend
-# Edit BACKEND_SCHEMA.mjs (rename to FRONTEND_SCHEMA.mjs if you prefer)
-# 3. Test it!
-git commit -m "test"
-# Guardian will validate automatically (<1s)
-```
-**What Guardian will check:**
-- ❌ No `console.log` in production code
-- ❌ No direct DOM manipulation in React components
-- ✅ Required imports (`react`, `react-dom`)
-- ✅ Required files (`tsconfig.json`, `vite.config.ts`)
-**Then customize:** Edit BACKEND_SCHEMA.mjs (rename to FRONTEND_SCHEMA.mjs if you prefer) to match YOUR folder structure, YOUR rules, YOUR tech stack.
-#### ⚙️ **Backend Developer (Node.js/Express/NestJS)**
-```bash
-# 1. Initialize Cerber (generates CERBER.md + guardian + health templates)
-npx cerber init --mode=dev
-# 2. Customize BACKEND_SCHEMA.mjs
-# Edit to match YOUR routes, YOUR layers, YOUR security rules
-# 3. Add health endpoint (see example below)
-```
-**Then customize:** Edit BACKEND_SCHEMA.mjs to match YOUR routes, YOUR layers, YOUR security rules.
-```javascript
-// server.js (ESM)
-import express from 'express';
-import { Cerber } from 'cerber-core/cerber';
-const app = express();
-// Define health checks
-const databaseCheck = async () => {
-  const isHealthy = await db.ping();
-  return isHealthy ? [] : [{
-    code: 'DB_DOWN',
-    severity: 'critical',
-    message: 'Database connection failed'
-  }];
-};
-// Create Cerber instance
-const cerber = new Cerber([databaseCheck]);
-// Health endpoint
-app.get('/api/health', async (req, res) => {
-  const result = await cerber.runChecks();
-  const statusCode = result.status === 'healthy' ? 200 : 500;
-  res.status(statusCode).json(result);
-});
-app.listen(3000);
-```
-**What you get:**
-- 🔍 `/api/health` endpoint for monitoring
-- 🚨 Automatic rollback on critical issues
-- 📊 Detailed diagnostics with root cause analysis
-#### ⚡ **SOLO Developer (Automation Scripts)**
-```bash
-# Add to package.json
-{
-  "scripts": {
-    "cerber:morning": "node node_modules/cerber-core/solo/scripts/cerber-morning.js",
-    "cerber:repair": "node node_modules/cerber-core/solo/scripts/cerber-auto-repair.js"
-  }
-}
-# Run daily dashboard
-npm run cerber:morning
-# Auto-fix issues
-npm run cerber:repair --dry-run
-```
-**What you get:**
-- 🌅 Daily dashboard (vulnerabilities, outdated deps, TODOs)
-- 🔧 Auto-repair (format, sync package-lock, fix imports)
-- 📈 Performance budget checks
-#### 👥 **TEAM Lead (Focus Mode for Large Codebases)**
-```bash
-# 1. Setup .cerber structure
-mkdir -p .cerber/modules
-cp -r node_modules/cerber-core/.cerber-example/* .cerber/
-# 2. Create module
-bash node_modules/cerber-core/team/scripts/cerber-add-module.sh pricing-engine
-# 3. Generate focus context (500 LOC instead of 10K LOC)
-bash node_modules/cerber-core/team/scripts/cerber-focus.sh pricing-engine
-# 4. Use with AI
-cat .cerber/FOCUS_CONTEXT.md
-# Share with ChatGPT/Claude - 10x faster responses!
-```
-**What you get:**
-- 🎯 **500 LOC context** instead of 10,000 LOC (10x faster AI)
-- 🗺️ Module boundaries (clear what belongs where)
-- 🔗 Connection contracts (how modules communicate)
-### Unified CLI
-All features available through unified CLI:
-```bash
-# Doctor - Setup validation (new in v1.1.7)
-npx cerber doctor              # Validate CERBER.md, schema, hooks, CI
-# Guardian - Pre-commit validation
-cerber guardian --schema ./SCHEMA.ts
-# Cerber - Health checks
-cerber health --checks ./health-checks.ts
-# SOLO - Daily dashboard
-cerber morning
-# SOLO - Auto-repair
-cerber repair --dry-run
-# TEAM - Focus mode
-cerber focus pricing-engine
-# Or use dedicated commands
-cerber-guardian
-cerber-health
-cerber-morning
-cerber-repair
-cerber-focus
-```
----
-## 🩺 npx cerber doctor (New in v1.1.7)
-Validate your Cerber setup before commits or deploys:
-```bash
-npx cerber doctor
-```
-**Exit codes:**
-- `0` ✅ All checks pass
-- `2` ❌ Missing CERBER.md
-- `3` ❌ Missing schema (strict mode only)
-- `4` ❌ Missing pre-commit hook or CI workflow
-**What it checks:**
-- CERBER.md present + valid YAML
-- Schema file exists (if `schema.mode: strict`)
-- `.husky/pre-commit` hook installed (if `guardian.enabled: true`)
-- GitHub Actions workflow present (if `ci.provider: github`)
-- Emergency override state (DISABLED | ACTIVE | EXPIRED | INVALID)
-**Example output:**
-```
-🩺 Cerber Doctor - Setup Validation
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-✓ CERBER.md: Found and valid
-✓ Schema: BACKEND_SCHEMA.mjs exists
-✓ Pre-commit hook: Installed (.husky/pre-commit)
-✓ CI workflow: Found (.github/workflows/cerber.yml)
-  Override: DISABLED
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-✅ All checks passed (exit 0)
-```
-**Use in CI:**
-```yaml
-- name: Validate Cerber setup
-  run: npx cerber doctor
+\```
 ```
-If doctor fails → build fails → prevents incomplete Cerber deployments.
----
-## ⚠️ Important: Schema Files Are NOT Source of Truth
-Before diving into examples below, understand this:
-**📋 Schema files (BACKEND_SCHEMA.mjs, FRONTEND_SCHEMA.mjs):**
-- Are **examples** and **optional templates**
-- Mirror YOUR architecture decisions from CERBER.md
-- Are user-owned and user-created (in strict mode)
-- Should be customized to YOUR project structure
-**📜 CERBER.md:**
-- Is the ONLY source of truth
-- Defines your roadmap, rules, team mode
-- Controls if/how Cerber helps with schema generation
-**Cerber does NOT design your system. The examples below show patterns - YOU decide which patterns fit YOUR architecture.**
+**Schema modes:**
+- `strict` (recommended) → You design architecture, Cerber guards it
+- `template_only` → Helper scaffold for beginners (NOT design decisions)
 ---
-### Guardian Setup (3 minutes)
-**1. Create architecture schema:**
-```javascript
-// BACKEND_SCHEMA.mjs
-export const BACKEND_SCHEMA = {
-  version: '1.0.0',
-  rules: [
-    {
-      name: 'Route files must import Router from express',
-      pattern: /routes\/.*\.ts$/,
-      requiredImports: ['Router', 'express'],
-      severity: 'error'
-    },
-    {
-      name: 'Protected routes must use authenticateToken',
-      pattern: /routes\/.*\.ts$/,
-      requiredImports: ['authenticateToken'],
-      exceptions: ['routes/public.ts'],
-      severity: 'error'
-    }
-  ]
-};
-```
-**2. Add pre-commit hook:**
-```bash
-# Pre-commit hook is automatically installed by npx cerber init
-# Or manually:
-npx husky add .husky/pre-commit "npm run cerber:guardian"
-```
-**3. Done!** Guardian now blocks commits that violate architecture rules.
-### Cerber Setup (2 minutes)
-**1. Add health endpoint:**
-```typescript
-// server.ts
-import { createHealthEndpoint } from 'cerber-core';
+## 📚 Documentation
-const healthChecks = {
-  database: async () => {
-    const result = await db.query('SELECT 1');
-    return result ? [] : [{ code: 'DB_DOWN', severity: 'critical' }];
-  },
-  redis: async () => {
-    const pong = await redis.ping();
-    return pong === 'PONG' ? [] : [{ code: 'REDIS_DOWN', severity: 'error' }];
-  }
-};
+**Quick Links:**
+- [📖 Full Documentation (Long README)](docs/README_LONG.md)
+- [🛡️ Guardian API](docs/GUARDIAN.md) - Pre-commit validation
+- [🔍 Cerber API](docs/CERBER.md) - Runtime health checks
+- [⚡ SOLO Layer](docs/SOLO.md) - Automation for solo developers (666 LOC)
+- [👥 TEAM Layer](docs/TEAM.md) - Focus Mode + module system (1861 LOC)
+- [🏗️ Architecture](docs/ARCHITECTURE.md) - System design philosophy
+- [🔐 Security Policy](SECURITY.md) - Supply-chain security, vulnerability reporting
+- [🤝 Contributing](CONTRIBUTING.md) - How to contribute
-app.get('/api/health', createHealthEndpoint(healthChecks));
-```
-**2. Deploy & monitor!**
-```bash
-curl https://your-api.com/api/health
-```
+**Workflows by Team Size:**
+- [Solo Developer](docs/workflows/solo-developer.md) - 1 person, 15min setup
+- [Small Team (2-5)](docs/workflows/small-team.md) - Module system, 1-2h setup
+- [Growing Team (5-20)](docs/workflows/growing-team.md) - Architecture governance
-```json
-{
-  "status": "healthy",
-  "summary": {
-    "totalChecks": 2,
-    "failedChecks": 0,
-    "criticalIssues": 0,
-    "errorIssues": 0,
-    "warningIssues": 0
-  },
-  "components": [
-    {
-      "name": "database",
-      "status": "healthy",
-      "durationMs": 12.4
-    }
-  ]
-}
-```
+**Examples:**
+- [Frontend Schema (React)](examples/frontend-schema.ts)
+- [Backend Schema (Express)](examples/backend-schema.ts)
+- [Health Checks](examples/health-checks.ts)
+- [SOLO Integration](examples/solo-integration/)
+- [TEAM Integration](examples/team-integration/)
 ---
-## ✨ Features
+## ✨ Key Features
 ### Guardian 1.0 (Pre-commit)
-- ✅ **Schema-as-Code** - Architecture rules in version control
-- ✅ **Fast feedback** - Catch errors in <1 second (vs 5 min CI wait)
-- ✅ **Required imports** - Enforce patterns across codebase
-- ✅ **Architect approvals** - Traceable exceptions with justification
-- ✅ **Framework-agnostic** - Works with Express, Fastify, NestJS
-- ✅ **Zero CI waste** - No more failed pipelines from trivial errors
+- Schema-as-Code (architecture rules in version control)
+- Fast feedback (<1s validation vs 5min CI wait)
+- Required imports + forbidden patterns
+- Architect approvals (traceable exceptions)
 ### Cerber 2.1 (Runtime)
+- Detailed diagnostics (diagnosis + rootCause + fix)
+- Severity levels (critical/error/warning)
+- Component-based health checks
+- Performance tracking
-- ✅ **Detailed diagnostics** - Not just status, but diagnosis + fix
-- ✅ **Severity levels** - critical/error/warning (block only when needed)
-- ✅ **Component-based** - Easy parsing for monitoring tools
-- ✅ **Performance tracking** - Duration metrics per check
-- ✅ **Database validation** - Schema, connections, migrations
-- ✅ **Integration checks** - External APIs, Cloudinary, Redis, etc.
----
-## 🏗️ Architecture
-```
-┌─────────────────────────────────────────────────────────┐
-│                     DEVELOPER                            │
-└─────────────────┬───────────────────────────────────────┘
-                  │
-                  ▼
-         ┌────────────────┐
-         │  git commit    │
-         └────────┬───────┘
-                  │
-                  ▼
-    ┌─────────────────────────┐
-    │  🛡️ Guardian 1.0        │  ◄─── Pre-commit validation
-    │  Architecture Validator  │
-    └─────────┬───────────────┘
-              │
-              ├─ ✅ Pass → Continue
-              │
-              └─ ❌ Fail → Block commit
-                           Show diagnostics
-                           Developer fixes
-         ┌────────────────┐
-         │  git push      │
-         └────────┬───────┘
-                  │
-                  ▼
-         ┌────────────────┐
-         │    CI/CD       │
-         │  (TypeScript,  │
-         │   Tests, etc)  │
-         └────────┬───────┘
-                  │
-                  ▼
-         ┌────────────────┐
-         │    Deploy      │
-         └────────┬───────┘
-                  │
-                  ▼
-    ┌─────────────────────────┐
-    │  🔍 Cerber 2.1         │  ◄─── Post-deploy validation
-    │  Health Diagnostics     │
-    └─────────┬───────────────┘
-              │
-              ├─ ✅ Healthy → Production OK
-              │
-              └─ ❌ Degraded → Alert + rollback option
-```
----
-## 📖 Guardian Examples
-### Example 1: Enforce Express Router in routes
-```javascript
-// BACKEND_SCHEMA.mjs
-{
-  name: 'Route files must import Router',
-  pattern: /routes\/.*\.ts$/,
-  requiredImports: [
-    'import { Router } from "express"',
-    'import express'
-  ],
-  severity: 'error'
-}
-```
-**Before Guardian:**
-```typescript
-// routes/users.ts ❌
-const app = require('express')(); // Wrong pattern!
-app.get('/users', ...);
-```
-**After Guardian:**
-```typescript
-// routes/users.ts ✅
-import { Router } from 'express';
-const router = Router();
-router.get('/users', ...);
-```
-### Example 2: Protected routes must have auth middleware
-```typescript
-{
-  name: 'Protected routes require authenticateToken',
-  pattern: /routes\/admin\/.*\.ts$/,
-  requiredImports: ['authenticateToken'],
-  severity: 'error'
-}
-```
-### Example 3: Architect approval for exceptions
-```typescript
-// routes/special-case.ts
-// ARCHITECT_APPROVED: Legacy endpoint - migration planned Q2 2026 - Stefan
-import legacyAuth from '../legacy/auth'; // Would normally be blocked
-```
----
-## 📖 Cerber Examples
-### Example 1: Database health check
-```typescript
-import { makeIssue } from 'cerber-core';
-export const databaseCheck = async () => {
-  try {
-    const result = await db.query('SELECT 1');
-    return []; // Healthy
-  } catch (err) {
-    return [
-      makeIssue({
-        code: 'DB_CONNECTION_FAILED',
-        component: 'database',
-        diagnosis: 'Cannot connect to PostgreSQL database',
-        rootCause: 'Connection string invalid or DB server down',
-        fix: 'Check DATABASE_URL env var and verify DB is running',
-        durationMs: 150.5,
-        details: { error: err.message }
-      })
-    ];
-  }
-};
-```
-**Response when unhealthy:**
-```json
-{
-  "status": "unhealthy",
-  "summary": {
-    "criticalIssues": 1,
-    "errorIssues": 0,
-    "warningIssues": 0
-  },
-  "components": [
-    {
-      "id": "DB_CONNECTION_FAILED",
-      "component": "database",
-      "status": "critical",
-      "message": "Cannot connect to PostgreSQL database",
-      "diagnosis": "Cannot connect to PostgreSQL database",
-      "rootCause": "Connection string invalid or DB server down",
-      "fix": "Check DATABASE_URL env var and verify DB is running",
-      "durationMs": 150.5,
-      "details": {
-        "error": "connect ECONNREFUSED 127.0.0.1:5432"
-      }
-    }
-  ]
-}
-```
-### Example 2: Integration check (Cloudinary)
-```typescript
-export const cloudinaryCheck = async () => {
-  if (!process.env.CLOUDINARY_API_KEY) {
-    return [
-      makeIssue({
-        code: 'CLOUDINARY_NOT_CONFIGURED',
-        component: 'cloudinary',
-        diagnosis: 'Cloudinary API key not set',
-        rootCause: 'Missing CLOUDINARY_API_KEY environment variable',
-        fix: 'Add CLOUDINARY_API_KEY to .env file',
-        severity: 'warning', // Non-blocking
-        durationMs: 0.5
-      })
-    ];
-  }
-  const ping = await cloudinary.api.ping();
-  return ping.status === 'ok' ? [] : [/* error */];
-};
-```
----
-## 🎛️ Configuration
-### Guardian Configuration
-```javascript
-// BACKEND_SCHEMA.mjs
-export const BACKEND_SCHEMA = {
-  version: '1.0.0',
-  // Forbidden patterns (will block commit)
-  forbiddenPatterns: [
-    { pattern: /console\.log/gi, name: 'CONSOLE_LOG' },
-    { pattern: /debugger;/gi, name: 'DEBUGGER' },
-    { pattern: /TODO_REMOVE/gi, name: 'TODO_REMOVE' }
-  ],
-  // Required imports per file pattern
-  requiredImports: {
-    'src/routes/**/*.ts': [
-      'import { Router } from "express"',
-      'import { authenticateToken }'
-    ],
-    'src/cerber/**/*.ts': [
-      'import { makeIssue, CerberIssueInstance }'
-    ]
-  },
-  // Architecture rules
-  rules: [
-    {
-      name: 'Cerber checks must use shared schema',
-      pattern: /cerber\/.*\.ts$/,
-      requiredImports: ['import.*shared/schema'],
-      forbiddenImports: ['import.*server/db/schema'],
-      severity: 'error'
-    }
-  ],
-  // Architect approvals (tracked exceptions)
-  approvals: [
-    {
-      file: 'src/legacy/auth.ts',
-      reason: 'Legacy code - migration planned Q2 2026',
-      approvedBy: 'Stefan Pitek',
-      date: '2026-01-02'
-    }
-  ]
-};
-```
+### SOLO Layer
+- Auto-repair (format, deps, changelog)
+- Performance budget enforcement
+- Daily dashboard
+- Dependency health checks
-### Cerber Configuration
-```typescript
-// cerber/health-checks.ts
-import { CerberCheck, makeIssue } from 'cerber-core';
-export const checks: Record<string, CerberCheck> = {
-  database: async () => {
-    // Returns: CerberIssueInstance[] (empty if healthy)
-  },
-  redis: async () => {
-    // Your Redis health check
-  },
-  cloudinary: async () => {
-    // Your Cloudinary check
-  }
-};
-// Route
-app.get('/api/health', async (req, res) => {
-  const results = await Promise.all(
-    Object.entries(checks).map(async ([name, check]) => ({
-      name,
-      issues: await check()
-    }))
-  );
-  const allIssues = results.flatMap(r => r.issues);
-  const critical = allIssues.filter(i => i.severity === 'critical').length;
-  const errors = allIssues.filter(i => i.severity === 'error').length;
-  const warnings = allIssues.filter(i => i.severity === 'warning').length;
-  const status = critical > 0 ? 'unhealthy' :
-                 errors > 0 ? 'degraded' : 'healthy';
-  res.status(status === 'healthy' ? 200 : 503).json({
-    status,
-    summary: { criticalIssues: critical, errorIssues: errors, warningIssues: warnings },
-    components: allIssues
-  });
-});
-```
+### TEAM Layer
+- **Focus Mode** (500 LOC context vs 10K LOC for AI) ⭐
+- Module boundaries enforcement
+- Connection contracts between modules
+- CERBER.md project mapping
 ---
-## 🔧 CI/CD Integration
+## 🚨 Emergency Override
-### GitHub Actions (Recommended)
+For **P0 production hotfixes only**, controlled safety fuse with strict TTL:
 ```yaml
-# .github/workflows/ci-cd.yml
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-      - run: npm ci
-      - run: npm run build
-  # E2E tests must pass before deploy
-  e2e:
-    needs: build
-    runs-on: ubuntu-latest
-    steps:
-      - run: npm test
-  # Deploy only if tests pass
-  deploy:
-    needs: [build, e2e]  # ✅ Blocks deploy if E2E fails
-    runs-on: ubuntu-latest
-    steps:
-      - run: echo "Deploying..."
-  # Cerber validates production health AFTER deploy
-  cerber-gatekeeper:
-    needs: deploy
-    runs-on: ubuntu-latest
-    steps:
-      - name: Wait for deployment
-        run: sleep 90
-      - name: Check production health
-        run: |
-          RESPONSE=$(curl -s https://api.example.com/api/health)
-          ERRORS=$(echo "$RESPONSE" | jq '.summary.errorIssues')
-          if [[ "$ERRORS" != "0" ]]; then
-            echo "❌ DEPLOYMENT BLOCKED - Health check failed"
-            exit 1
-          fi
-          echo "✅ Production healthy"
-```
----
-## 📊 Real-world Impact
-### Case Study: Eliksir Backend (January 2, 2026)
-**Session timeline:**
-```yaml
-Problems encountered:
-  - 35 TypeScript compilation errors
-  - Schema sync mismatch (shared vs server/db/schema)
-  - node-fetch ESM compatibility issue
-  - Missing is_active column in production
-  - 14/19 E2E tests failing (cold start)
-  - Workflow security gap (deploy before E2E)
-  - Cloudinary blocking deployment
-  - API format mismatch (Cerber 2.0 → 2.1)
-Time to resolution:
-  WITHOUT Guardian + Cerber: 80 minutes (estimated)
-  WITH Guardian + Cerber: 32 minutes (actual)
-Time saved: 48 minutes (60% reduction)
-Issues caught pre-commit: 35 (TypeScript, imports, patterns)
-Issues caught post-deploy: 1 (Cloudinary severity)
-Production incidents prevented: 2 (schema mismatch, missing column)
-ROI: 2.5x time saved on first day of use
-```
-**Developer experience:**
-```diff
-- ❌ Push → Wait 5 min → CI fails → Fix → Repeat 6x
-+ ✅ Commit blocked instantly → Fix → Commit passes → Deploy once
-```
----
-## 🤝 Contributing
-Contributions welcome! Please:
-1. Fork the repo
-2. Create feature branch (`git checkout -b feature/amazing`)
-3. Commit with Guardian validation (`git commit -m 'feat: add amazing feature'`)
-4. Push (`git push origin feature/amazing`)
-5. Open Pull Request
-**Development setup:**
-```bash
-git clone https://github.com/Agaslez/cerber-core.git
-cd cerber-core
-npm install
-npm run test
-```
----
-## 🗺️ Roadmap
-### v1.1 (Q1 2026)
-- [ ] TypeScript full type definitions
-- [ ] Jest integration (run checks in tests)
-- [ ] VS Code extension (real-time validation)
-- [ ] npm package publication
-### v1.2 (Q2 2026)
-- [ ] Slack/Discord notifications
-- [ ] Grafana dashboard integration
-- [ ] Auto-remediation for common issues
-- [ ] Multi-language support (Python, Go, Java)
-### v2.0 (Q3 2026)
-- [ ] AI-powered diagnostics (suggest fixes)
-- [ ] Historical health trends
-- [ ] Load testing integration
-- [ ] Kubernetes operator
----
-## 📚 Resources
-- **Documentation:** https://github.com/Agaslez/cerber-core/wiki
-- **Examples:** https://github.com/Agaslez/cerber-core/tree/main/examples
-- **Issues:** https://github.com/Agaslez/cerber-core/issues
-- **Discussions:** https://github.com/Agaslez/cerber-core/discussions
----
-## 📄 License
-MIT © 2026 Stefan Pitek
----
-## 🌟 Show Your Support
-If Cerber Core saved you time, give it a ⭐ on GitHub!
-**Built with ❤️ by Stefan Pitek**
----
-## 🔗 Related Projects
-- [Husky](https://github.com/typicode/husky) - Git hooks made easy
-- [lint-staged](https://github.com/okonet/lint-staged) - Run linters on staged files
-- [ArchUnit](https://www.archunit.org/) - Architecture testing (Java)
-- [express-healthcheck](https://github.com/lennym/express-healthcheck) - Basic health checks
-**What makes Cerber Core unique?**
-- 🆕 Dual-layer protection (pre-commit + runtime)
-- 🆕 Detailed diagnostics (not just status codes)
-- 🆕 Architect approval system
-- 🆕 Schema-as-Code architecture
-- 🆕 Framework-agnostic
----
-## 🆕 Cerber SOLO - Automation for Solo Developers
-**New in v2.0:** Cerber SOLO extends Guardian + Cerber with automation tools for solo developers.
-### What's New
-- **Auto-repair** - Fixes package.json, .env.example, CHANGELOG automatically
-- **Performance budget** - Enforces bundle size limits
-- **Dependency health** - Weekly security & deprecation checks
-- **Documentation sync** - Validates code vs docs
-- **Feature flags** - Toggle features without redeploy
-- **Daily dashboard** - Morning health overview
-- **Smart rollback** - Surgical file rollback
-[📖 Read SOLO documentation](docs/SOLO.md)
-### Quick Start (SOLO)
-```bash
-# Install SOLO tools (already included in cerber-core)
-npm install cerber-core --save-dev
-# Add SOLO scripts to package.json
-# (See examples/solo-integration/package.json)
-# Daily workflow
-npm run cerber:morning      # Start day (2 min)
-npm run cerber:repair       # Auto-fix issues
-npm run cerber:pre-push     # Before push (3 min)
-npm run cerber:snapshot     # End of day
-```
-### SOLO + Guardian Integration
-Cerber SOLO works **alongside** your existing Guardian setup:
-```
-Morning:
-  npm run cerber:morning       # SOLO dashboard
-Development:
-  git commit                   # Guardian validates (pre-commit)
-  npm run cerber:repair        # SOLO auto-fixes
-Before Push:
-  npm run cerber:pre-push      # SOLO full check
-Deploy:
-  curl /api/health             # Cerber 2.1 validates
-```
-[See full integration guide →](examples/solo-integration)
----
-## 🆕 Cerber TEAM - Team Collaboration Layer
-**New in v2.0:** Cerber TEAM adds module system and focus mode for teams working on large codebases.
-### What's New
-- **Module System** - Clear boundaries between components
-- **Focus Mode** - AI gets 500 LOC context instead of 10,000 LOC (10x faster)
-- **Connection Contracts** - Explicit interfaces between modules
-- **BIBLE.md** - Master project map
-- **Module Validation** - Enforce boundaries, prevent cross-contamination
-[📖 Read TEAM documentation](docs/TEAM.md)
-### Quick Start (TEAM)
-```bash
-# Create module
-bash team/scripts/cerber-add-module.sh pricing-engine
-# Work on module (focus!)
-bash team/scripts/cerber-focus.sh pricing-engine
-cat .cerber/FOCUS_CONTEXT.md    # Only 500 LOC!
-# Validate
-bash team/scripts/cerber-module-check.sh pricing-engine
-bash team/scripts/cerber-connections-check.sh
-# Commit
-git commit                      # Guardian validates
-```
----
-## 🏆 Why Cerber Core?
-### Unique Innovations
-#### 1. Architect Approval System
-The only pre-commit tool with inline approval tracking:
-```typescript
-// ❌ Without approval - BLOCKED
-console.log('debug info');
-// ✅ With approval - ALLOWED + TRACKED
-// ARCHITECT_APPROVED: Debugging cold start issue - 2026-01-02 - Stefan
-console.log('debug info');
-```
-**Benefits:**
-- Flexibility when rules need exceptions
-- Inline documentation of why exceptions exist
-- Audit trail for architecture decisions
-- Easy cleanup when exceptions no longer needed
-#### 2. Dual-Layer Validation
-```
-Guardian (pre-commit) → catches 90% of issues
-    ↓
-Cerber (runtime) → catches remaining 10%
-    ↓
-Result: 95%+ detection rate
-```
-#### 3. Focus Mode for AI ⭐
-**Problem:** AI needs 10,000 LOC of context, making it slow and expensive.
-**Solution:** Generate focused 500 LOC context for specific modules.
-```bash
-cerber-focus pricing-engine
-# Generates: .cerber/FOCUS_CONTEXT.md
-# Share with AI instead of entire codebase
-# Result: 10x faster responses, better accuracy
-```
-**What's included:**
-- Module documentation (MODULE.md)
-- Public interface (contract.json)
-- Dependencies (dependencies.json)
-- Related connections
-- Recent changes
----
-## � Real-World Examples
-**Want to see Cerber in action?**
-**[→ Real Workflows from Eliksir Project](docs/REAL_WORKFLOWS.md)** ⭐
-Real production session (January 2, 2026) showing:
-- ✅ **Morning routine** - 2 min → complete context (vs 8+ min manual)
-- ✅ **Auto-repair** - 30 sec → dependencies + format (vs 20 min manual)
-- ✅ **Focus Mode** - 8s AI response (vs 60s with full codebase)
-- ✅ **Guardian blocks** - 2 bugs prevented (debug code + missing import)
-- ✅ **Cerber gatekeeper** - 1 production incident prevented (DB config)
-- ✅ **Time saved** - 4.5 hours in one day
-- ✅ **ROI** - 230% on Day 1
-```
-💰 COST-BENEFIT ANALYSIS
-Setup: 4 hours (one-time)
-Saved: 1.2 hours + 12 hours (bugs prevented) = 13.2 hours
-ROI = (13.2 - 4) / 4 = 230%
-Break-even: Day 1 ✅
-```
-**Workflow Guides by Team Size:**
-- [**Solo Developer**](docs/workflows/solo-developer.md) - 1 person, 15 min setup, 1+ hour saved/day
-- [**Small Team (2-5)**](docs/workflows/small-team.md) - Module system, 1-2 hours setup, 2-3 hours saved/dev/day
-- [**Growing Team (5-20)**](docs/workflows/growing-team.md) - Architecture governance, 1-2 days setup, 3-5 hours saved/dev/day
-**Track Your Progress:**
-- [**Monthly Report Template**](docs/MONTHLY_REPORT_TEMPLATE.md) - Track metrics, ROI, wins & learnings
----
-## �📚 Documentation
-- [**Guardian API Reference**](docs/GUARDIAN.md) - Complete Guardian documentation
-- [**Cerber API Reference**](docs/CERBER.md) - Runtime health checks guide
-- [**SOLO Documentation**](docs/SOLO.md) - Automation tools (666 LOC guide)
-- [**TEAM Documentation**](docs/TEAM.md) - Collaboration layer (1861 LOC guide)
-- [**Architecture Overview**](docs/ARCHITECTURE.md) - System design & philosophy
-- [**Contributing Guide**](CONTRIBUTING.md) - How to contribute
----
-## 💡 Examples
-> ⚠️ **Remember:** Examples show patterns, NOT decisions. Copy and customize to YOUR architecture defined in CERBER.md.
-### Complete Examples in `/examples`
-- [**Frontend (React + Guardian)**](examples/frontend-schema.ts) - React/Vue patterns (customize to your structure)
-- [**Backend (Express + Cerber)**](examples/backend-schema.ts) - Node.js/Express patterns (customize to your layers)
-- [**Health Checks**](examples/health-checks.ts) - 6 production-ready checks
-- [**SOLO Integration**](examples/solo-integration/) - Automation setup
-- [**TEAM Integration**](examples/team-integration/) - Module system setup
-### Quick Example: Guardian Schema
-```typescript
-// FRONTEND_SCHEMA.ts
-export const SCHEMA = {
-  requiredFiles: [
-    'src/lib/config.ts',
-    'package.json',
-  ],
-  forbiddenPatterns: [
-    {
-      pattern: /console\.log\s*\(/gi,
-      name: 'CONSOLE_LOG',
-      exceptions: ['tests/', '.spec.'],
-      severity: 'warning'
-    },
-    {
-      pattern: /fetch\(/gi,
-      name: 'DIRECT_FETCH',
-      exceptions: ['src/lib/api.ts'],
-      severity: 'error'
-    },
-  ],
-  requiredImports: {
-    'src/components/Calculator.tsx': [
-      "import { API } from '../lib/config'",
-    ],
-  },
-};
-```
-### Quick Example: Cerber Health Checks
-```typescript
-import { makeIssue, CerberCheck } from 'cerber-core/cerber';
-export const checkDatabase: CerberCheck = async (ctx) => {
-  try {
-    await db.query('SELECT 1');
-    return []; // No issues
-  } catch (err) {
-    return [makeIssue({
-      code: 'DB_CONNECTION_FAILED',
-      component: 'Database',
-      severity: 'critical',
-      message: `Cannot connect to database: ${err.message}`,
-      rootCause: err.stack,
-      fix: 'Verify DATABASE_URL and database server status',
-    })];
-  }
-};
-```
----
-## 🚀 Advanced Usage
-### SOLO - Daily Automation
-```bash
-# Morning routine
-cerber-morning
-# Shows:
-# - Git status
-# - Dependency health
-# - Performance metrics
-# - TODO reminders
-# Auto-repair issues
-cerber-repair --dry-run    # Preview fixes
-cerber-repair              # Apply fixes
-# Dependency health
-cerber-deps-health
-# Checks:
-# - Outdated packages
-# - Security vulnerabilities
-# - License compliance
-# Performance budget
-cerber-performance-budget
-# Enforces bundle size limits
-```
-### TEAM - Module System
-```bash
-# Create new module
-bash team/scripts/cerber-add-module.sh payment-gateway
-# Work on module (Focus Mode)
-cerber-focus payment-gateway
-# Generates .cerber/FOCUS_CONTEXT.md (500 LOC)
-# Share with AI for 10x faster development
-# Validate module
-bash team/scripts/cerber-module-check.sh payment-gateway
-# Validate all connections
-bash team/scripts/cerber-connections-check.sh
-# Morning team briefing
-bash team/scripts/cerber-team-morning.sh
-```
----
-## � Support This Project
-If Cerber Core saved you time, prevented bugs, or improved your codebase quality, consider supporting its development!
-### 🌟 GitHub Sponsors
-<a href="https://github.com/sponsors/Agaslez">
-  <img src="https://img.shields.io/badge/Sponsor-❤️_Sponsor-ea4aaa?style=for-the-badge&logo=github-sponsors&logoColor=white" alt="GitHub Sponsors">
-</a>
-**Why sponsor?**
-- ✅ Keeps the project actively maintained
-- ✅ Funds new features and improvements
-- ✅ Priority support for sponsors
-- ✅ Your logo in README (Silver+ tiers)
-- ✅ Influence development roadmap
-**Sponsorship Tiers:**
-- **☕ Coffee ($5/month):** Sponsor badge, access to sponsor discussions
-- **🥉 Bronze ($25/month):** Everything above + small logo in README + priority support (24h)
-- **🥈 Silver ($100/month):** Everything above + medium logo + priority support (12h) + monthly consultation call
-- **🥇 Gold ($500/month):** Everything above + large logo (top position) + priority support (4h) + custom feature requests
-- **💎 Platinum ($2,500/month):** Everything above + dedicated support + weekly calls + custom integrations
-### 💼 Professional Services
-Need help integrating Cerber Core into your organization?
-**Available Services:**
-- **🎓 Team Training** (5-10 developers): $2,500
-  - Half-day workshop on Guardian, Cerber, and Focus Mode
-  - Best practices for architecture enforcement
-  - Custom schema creation for your stack
-- **💼 Enterprise Integration** (custom pricing)
-  - Full integration with your CI/CD pipeline
-  - Custom health checks for your infrastructure
-  - Team Focus Mode setup and training
-  - Ongoing support and consultation
-- **🚀 1-on-1 Consultation**: $200/hour
-  - Schema design review
-  - Architecture strategy session
-  - Troubleshooting and optimization
-**Contact:** st.pitek@gmail.com
-### ☕ One-Time Donation
-Prefer a one-time contribution? Buy me a coffee!
-<a href="https://www.buymeacoffee.com/stefanpitek">
-  <img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" height="50" alt="Buy Me A Coffee">
-</a>
----
-## 🏢 Sponsors
-### 💎 Platinum Sponsors
-**Become the first Platinum sponsor!** Your logo here + dedicated support.
-### 🥇 Gold Sponsors
-**Become the first Gold sponsor!** Your logo here + priority support + monthly calls.
-### 🥈 Silver Sponsors
-**Become the first Silver sponsor!** Your logo here + priority support.
-### 🥉 Bronze Sponsors
-*Your name here* - Support Cerber Core development!
----
-## �🔧 Configuration
-### Guardian Configuration
-```typescript
-// SCHEMA.ts
-export interface GuardianSchema {
-  requiredFiles?: string[];
-  forbiddenPatterns?: ForbiddenPattern[];
-  requiredImports?: Record<string, string[]>;
-  packageJsonRules?: {
-    requiredScripts?: string[];
-    requiredDependencies?: string[];
-    requiredDevDependencies?: string[];
-  };
-}
+## CERBER_OVERRIDE
+enabled: true
+reason: "P0 - Payment API down, emergency rollback"
+expires: "2026-01-04T18:00:00Z"  # 6-hour TTL
+approvedBy: "CTO Name"
 ```
-### Cerber Configuration
+**What Override DOES:**
+- ✅ Allows pre-commit to pass WITH WARNING (audit trail logged)
+- ✅ Can skip postDeploy gate if configured
-```typescript
-// health-checks.ts
-import type { CerberCheck } from 'cerber-core/cerber';
+**What Override NEVER DOES:**
+- ❌ Disable `cerber-integrity` job (self-protection always runs)
+- ❌ Disable entire CI pipeline (build/test/lint must pass)
+- ❌ Disable CODEOWNERS enforcement (team mode)
-export const checks: CerberCheck[] = [
-  checkDatabase,
-  checkRedis,
-  checkExternalAPI,
-  checkDiskSpace,
-  checkMemory,
-];
-```
+**Use sparingly.** After expiry, guardian proceeds with normal validation.
 ---
 ## 🤝 Contributing
-We welcome contributions! Here's how:
-1. **Read** [CONTRIBUTING.md](CONTRIBUTING.md)
-2. **Fork** the repository
-3. **Create** a feature branch
-4. **Make** your changes
-5. **Test** locally
-6. **Submit** a pull request
-### Development Setup
+Contributions welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) first.
 ```bash
 git clone https://github.com/Agaslez/cerber-core.git
@@ -1634,260 +266,38 @@ npm test
 ---
-## � Security
-Security is a top priority for Cerber Core. We take the security of our users seriously.
-### Reporting Security Issues
-**⚠️ DO NOT create public issues for security vulnerabilities.**
-If you discover a security issue, please email: **st.pitek@gmail.com**
-Include:
-- Description of the vulnerability
-- Steps to reproduce
-- Potential impact
-- Your contact information
-**Response time:** 24-48 hours acknowledgment, 7-14 days for fix.
----
-## 🚨 Emergency Override (New in v1.1.7)
-For **critical production hotfixes only** (P0 incidents), Cerber provides a **controlled safety fuse** with strict time limits.
-### What Override DOES ✅
-- Allows pre-commit to pass **WITH WARNING** (audit trail logged)
-- Can skip `postDeploy` gate if configured
-- Requires: reason, expiry timestamp (TTL), approver name
-- Automatically expires (guardian validates TTL)
-### What Override NEVER DOES ❌
-Override is a **safety fuse**, NOT a power switch. It **NEVER** disables:
-- ❌ `cerber-integrity` job (self-protection always runs)
-- ❌ Entire CI pipeline (build, test, lint must pass)
-- ❌ `cerber-ci` workflow job (contract validation always runs)
-- ❌ CODEOWNERS enforcement (team mode protection)
-### Example: P0 Hotfix
-```yaml
-## CERBER_OVERRIDE
-enabled: true
-reason: "P0 - Payment API down, emergency rollback required"
-expires: "2026-01-04T18:00:00Z"  # 6-hour TTL
-approvedBy: "CTO Stefan"
-```
-**Guardian behavior:**
-```bash
-git commit -m "fix: rollback payment API to v1.2.3"
-⚠️  CERBER EMERGENCY OVERRIDE ACTIVE
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Reason:     P0 - Payment API down, emergency rollback required
-Expires:    2026-01-04T18:00:00Z (5h 23m remaining)
-Approved:   CTO Stefan
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Guardian checks: BYPASSED WITH WARNING
-Self-protection: STILL ACTIVE (cerber-integrity runs)
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-[main 3a7f2e9] fix: rollback payment API to v1.2.3
-```
-**CI behavior:**
-- ✅ `cerber-integrity` job **runs** (validates CERBER.md, override metadata)
-- ✅ Build, test, lint jobs **run**
-- ✅ `cerber-ci` job **runs** (contract validation)
-- ⚠️ Override warning shown in CI logs (audit trail)
-**After expiry:**
-```bash
-git commit -m "feat: add new feature"
-❌ CERBER EMERGENCY OVERRIDE EXPIRED
-Override expired at: 2026-01-04T18:00:00Z
-Proceeding with normal validation...
-❌ Schema validation failed: Missing type annotation for handlePayment()
-```
-### Verification
-```bash
-npx cerber doctor
-# Shows: Override: ACTIVE (expires 2026-01-04T18:00:00Z)
-# Or: Override: EXPIRED (expired 2h ago)
-# Or: Override: DISABLED
-```
-### Rules
-1. **All fields required:** enabled, reason, expires, approvedBy (missing = invalid = disabled)
-2. **TTL enforced:** Guardian checks expiry timestamp (expired = proceeds with normal validation)
-3. **Audit trail:** All commits with active override logged with full metadata
-4. **No carte blanche:** Hard limits enforced (integrity, CI, CODEOWNERS never bypassed)
-**Use sparingly.** Override is for emergencies, not convenience.
----
-### Security Features
-✅ **No External Calls:** Guardian and Cerber run locally, no data sent externally
-✅ **Open Source:** Full transparency - audit the code yourself
-✅ **No Telemetry:** No tracking, no analytics, no data collection
-✅ **MIT Licensed:** Safe for commercial use
-✅ **Supply-Chain Hardened:** 2FA, CI-only publishing, no risky lifecycle scripts (v1.1.7)
-✅ **Path Safety:** Generator writes only to repo root, whitelist-validated paths (v1.1.7)
-### Best Practices
-- Never commit secrets to schemas (use `process.env`)
-- Keep `.env` files in `.gitignore`
-- Update regularly: `npm update cerber-core`
-- Enable Dependabot for automated security updates
-- Run `npm audit` regularly
-- Review CERBER.md changes in PRs (protected by CODEOWNERS in team mode)
-- Use emergency override sparingly (P0 incidents only)
-**Full security policy:** [SECURITY.md](SECURITY.md) (includes supply-chain security, vulnerability reporting, supported versions)
----
-## 📄 License
-MIT © 2026 Stefan Pitek
-See [LICENSE](LICENSE) for details.
-### Commercial Use
-Cerber Core is free for commercial use under MIT License. No attribution required (but appreciated!).
-**Need:**
-- Custom features or private fork support?
-- Dedicated SLA or priority bug fixes?
-- On-premises deployment assistance?
-- Enterprise training and integration?
-**Contact:** st.pitek@gmail.com
----
-## 🌟 Acknowledgments
-- Inspired by pre-commit framework
-- Tested in production at Eliksir SaaS
-- Built with TypeScript + Node.js
-- Community feedback from 100+ developers
----
 ## 📞 Support
 - 🐛 **Issues:** [GitHub Issues](https://github.com/Agaslez/cerber-core/issues)
 - 💡 **Discussions:** [GitHub Discussions](https://github.com/Agaslez/cerber-core/discussions)
+- 📖 **Docs:** [Full Documentation](docs/README_LONG.md)
+- 🔐 **Security:** Report vulnerabilities to st.pitek@gmail.com
 - ⭐ **Repository:** [cerber-core](https://github.com/Agaslez/cerber-core)
 ---
-## 🎯 Roadmap
+## 📄 License
-### Version 1.1 (Q1 2026)
-- [ ] VS Code Extension (visual dashboard)
-- [ ] GitHub Action (automated checks in CI)
-- [ ] Slack/Discord notifications
-- [ ] Web dashboard (React app)
+MIT © 2026 Stefan Pitek
-### Version 2.0 (Q2 2026)
-- [ ] Playwright integration (E2E health checks)
-- [ ] Custom reporter plugins
-- [ ] Metrics export (Prometheus, DataDog)
-- [ ] Multi-language support (Python, Go)
+Free for commercial use. See [LICENSE](LICENSE) for details.
 ---
-## ⭐ Star History
-If Cerber saved you time, please give us a star! ⭐
+## 🌟 About
-[![Star History Chart](https://api.star-history.com/svg?repos=Agaslez/cerber-core&type=Date)](https://star-history.com/#Agaslez/cerber-core)
+Founded by **Agata Ślęzak**, created by **Stefan Pitek**
----
-### Integration
-```
-Morning:
-  npm run cerber:morning         # SOLO + TEAM dashboard
-Create module:
-  bash team/scripts/cerber-add-module.sh payment
-Focus mode:
-  bash team/scripts/cerber-focus.sh payment
-  # AI gets FOCUS_CONTEXT.md (500 LOC vs 10,000 LOC)
-Validate:
-  bash team/scripts/cerber-module-check.sh payment
-  bash team/scripts/cerber-connections-check.sh
-Commit:
-  git commit                     # Guardian validates
-Before push:
-  npm run cerber:pre-push        # SOLO checks
-Deploy:
-  curl /api/health               # Cerber 2.1 validates
-```
+Read the full story: [docs/STORY.md](docs/STORY.md)
-[See full integration guide →](examples/team-integration)
+**Support development:** [docs/SPONSORING.md](docs/SPONSORING.md)
 ---
 <div align="center">
-**[⬆ Back to top](#-cerber-core)**
+⭐ **If Cerber saved you time, give it a star!** ⭐
 Made with 🛡️ by developers, for developers
----
-## 👥 About the Project
-**Founded by Agata Ślęzak**, created and developed by **Stefan Pitek**
-### 🎯 The Story
-**Stefan Pitek** - Career changer who started coding in May 2025
-- 30 years professional experience: 12 years banking, 8 years hospitality, 8 years business, 2 years as chef
-- Co-owned restaurant with Agata
-- First line of code: May 2025
-- 8 months later: 3 production SaaS apps + this open-source tool
-- Built entirely with AI assistance (Claude, ChatGPT, Copilot)
-**Agata Ślęzak** - Business owner and project sponsor
-- Former restaurant co-owner
-- Provides business direction and funding
-- Handles legal and financial aspects
-- **Most importantly:** Believed in Stefan's potential when he had zero coding experience
-- Continues to support and encourage through every challenge
-**Partnership:** 90/10 split reflecting business ownership and technical contribution.
-> *"None of this would exist without Agata's unwavering belief and support. When I wrote my first `console.log`, she saw a future developer. Eight months later, here we are."* — Stefan
-**From restaurants to SaaS** - bringing the same attention to quality and customer experience that we learned in hospitality.
 </div>