laravel-permission

# Laravel Permission (Spatie)

## Agent Workflow (MANDATORY)

Before ANY implementation, launch in parallel:

1. **fuse-ai-pilot:explore-codebase** - Check existing auth patterns
2. **fuse-ai-pilot:research-expert** - Verify Spatie Permission docs via Context7
3. **mcp__context7__query-docs** - Check Laravel authorization patterns

After implementation, run **fuse-ai-pilot:sniper** for validation.

---

## Overview

Spatie Laravel Permission provides complete role-based access control (RBAC) for Laravel applications.

| Component | Purpose |
|-----------|---------|
| **Role** | Group of permissions (admin, writer) |
| **Permission** | Single ability (edit articles) |
| **Middleware** | Route protection |
| **Blade Directives** | UI authorization |
| **Teams** | Multi-tenant scoping |
| **Wildcards** | Hierarchical permissions |
| **Super Admin** | Bypass all checks |
| **Events** | Audit logging (v6.15.0+) |
| **Query Scopes** | Filter users by role/permission |
| **API Support** | Sanctum/Passport integration |
| **Policies** | Resource-based authorization |

---

## Critical Rules

1. **Seed roles/permissions** in `DatabaseSeeder`
2. **Cache reset** after changes: `php artisan permission:cache-reset`
3. **Use kebab-case** for naming: `edit-articles`
4. **Never hardcode** role checks in controllers - use middleware
5. **Set team context** early in request for multi-tenant apps
6. **Specify guard for API** - `permission:edit,api`
7. **Clear cache in tests** - Reset in setUp()/beforeEach()

---

## Reference Guide

### Core Concepts

| Topic | Reference | When to consult |
|-------|-----------|-----------------|
| **Setup** | [spatie-permission.md](references/spatie-permission.md) | Installation, model setup, core methods |
| **Middleware** | [middleware.md](references/middleware.md) | Route protection patterns |
| **Blade** | [blade-directives.md](references/blade-directives.md) | UI authorization directives |
| **Direct vs Role** | [direct-permissions.md](reference