Add scope documentation and update extensions docs

docs/extensions.md

···
 | `AtpClient::hasDomainExtension($domain, $name)` | Check if a request client extension is registered |
 | `AtpClient::flushExtensions()` | Clear all extensions (useful for testing) |
 
-The same methods are available on `AtpPublicClient` for unauthenticated extensions.
-
 ### Extension Types
 
 | Type | Access Pattern | Use Case |
···
 ```bash
 # Create a domain client extension
 php artisan make:atp-client AnalyticsClient
-
-# Create a public domain client extension
-php artisan make:atp-client DiscoverClient --public
 
 # Create a request client extension for an existing domain
 php artisan make:atp-request MetricsClient --domain=bsky
-
-# Create a public request client extension
-php artisan make:atp-request TrendingClient --domain=bsky --public
 ```
 
 The generated files are placed in configurable directories. You can customize these paths in `config/client.php`:
···
 ```php
 'generators' => [
     'client_path' => 'app/Services/Clients',
-    'client_public_path' => 'app/Services/Clients/Public',
     'request_path' => 'app/Services/Clients/Requests',
-    'request_public_path' => 'app/Services/Clients/Public/Requests',
 ],
 ```
 
···
 $authorMetrics = $client->bsky->metrics->getAuthorMetrics('someone.bsky.social');
 ```
 
-## Public Client Extensions
+## Public vs Authenticated Mode
 
-The `AtpPublicClient` supports the same extension system for unauthenticated API access:
+The `AtpClient` class works in both public and authenticated modes. Both `Atp::public()` and `Atp::as()` return the same `AtpClient` class:
 
 ```php
-use SocialDept\AtpClient\Client\Public\AtpPublicClient;
-
-// Domain client extension
-AtpPublicClient::extend('discover', fn($atp) => new DiscoverClient($atp));
+// Public mode - no authentication
+$publicClient = Atp::public('https://public.api.bsky.app');
+$publicClient->bsky->actor->getProfile('someone.bsky.social');
 
-// Request client extension on existing domain
-AtpPublicClient::extendDomain('bsky', 'trending', fn($bsky) => new TrendingClient($bsky));
+// Authenticated mode - with session
+$authClient = Atp::as('did:plc:xxx');
+$authClient->bsky->actor->getProfile('someone.bsky.social');
 ```
 
-For public request clients, extend `PublicRequest` instead of `Request`:
-
-```php
-<?php
-
-namespace App\Atp;
-
-use SocialDept\AtpClient\Client\Public\Requests\PublicRequest;
-
-class TrendingPublicClient extends PublicRequest
-{
-    public function getPopularFeeds(int $limit = 10): array
-    {
-        return $this->atp->bsky->feed->getPopularFeedGenerators($limit)->feeds;
-    }
-}
-```
+Extensions registered on `AtpClient` work in both modes. The underlying HTTP layer automatically handles authentication based on whether a session is present.
 
 ## Registering Multiple Extensions
 
···
     AtpClient::extendDomain('bsky', 'metrics', fn($bsky) => new BskyMetricsClient($bsky));
     AtpClient::extendDomain('bsky', 'lists', fn($bsky) => new BskyListsClient($bsky));
     AtpClient::extendDomain('atproto', 'backup', fn($atproto) => new RepoBackupClient($atproto));
-
-    // Public client extensions
-    AtpPublicClient::extend('discover', fn($atp) => new DiscoverClient($atp));
 }
 ```
 
···
     }
 }
 ```
+
+### Documenting Scope Requirements
+
+Use the `#[RequiresScope]` attribute to document which OAuth scopes your extension methods require. This helps with documentation and enables scope checking in authenticated mode:
+
+```php
+use SocialDept\AtpClient\Attributes\RequiresScope;
+use SocialDept\AtpClient\Client\Requests\Request;
+use SocialDept\AtpClient\Enums\Scope;
+
+class BskyMetricsClient extends Request
+{
+    #[RequiresScope(Scope::TransitionGeneric, granular: 'rpc:app.bsky.feed.getTimeline')]
+    public function getTimelineMetrics(): array
+    {
+        $timeline = $this->atp->bsky->feed->getTimeline();
+        // Process and return metrics...
+    }
+
+    // Methods without #[RequiresScope] work in both public and authenticated modes
+    public function getPublicPostMetrics(string $uri): array
+    {
+        $thread = $this->atp->bsky->feed->getPostThread($uri);
+        // Process and return metrics...
+    }
+}
+```
+
+Methods with `#[RequiresScope]` indicate they require authentication, while methods without it can work in public mode. See [scopes.md](scopes.md) for full documentation on scope handling.
 
 ## Available Domains
 

docs/scopes.md

···
+# OAuth Scopes
+
+The AT Protocol uses OAuth scopes to control what actions an application can perform on behalf of a user. AtpClient provides tools for documenting, checking, and enforcing scope requirements.
+
+## Quick Reference
+
+### Scope Enum
+
+```php
+use SocialDept\AtpClient\Enums\Scope;
+
+// Transition scopes (current AT Protocol scopes)
+Scope::Atproto              // 'atproto' - Full access
+Scope::TransitionGeneric    // 'transition:generic' - General API access
+Scope::TransitionEmail      // 'transition:email' - Email access
+Scope::TransitionChat       // 'transition:chat.bsky' - Chat access
+
+// Granular scope builders (future AT Protocol scopes)
+Scope::repo('app.bsky.feed.post', ['create', 'delete'])  // Record operations
+Scope::rpc('app.bsky.feed.getTimeline')                  // RPC endpoint access
+Scope::blob('image/*')                                    // Blob upload access
+Scope::account('email')                                   // Account attribute access
+Scope::identity('handle')                                 // Identity attribute access
+```
+
+### RequiresScope Attribute
+
+```php
+use SocialDept\AtpClient\Attributes\RequiresScope;
+use SocialDept\AtpClient\Enums\Scope;
+
+#[RequiresScope(Scope::TransitionGeneric)]
+public function getTimeline(): GetTimelineResponse
+{
+    // Method implementation
+}
+```
+
+## Understanding AT Protocol Scopes
+
+### Current Transition Scopes
+
+The AT Protocol is currently in a transition period where broad "transition scopes" are used:
+
+| Scope | Description |
+|-------|-------------|
+| `atproto` | Full access to the AT Protocol |
+| `transition:generic` | General API access for most operations |
+| `transition:email` | Access to email-related operations |
+| `transition:chat.bsky` | Access to Bluesky chat features |
+
+### Future Granular Scopes
+
+The AT Protocol is moving toward granular scopes that provide fine-grained access control:
+
+```php
+// Record operations
+'repo:app.bsky.feed.post'                      // All operations on posts
+'repo:app.bsky.feed.post?action=create'        // Only create posts
+'repo:app.bsky.feed.like?action=create&action=delete'  // Create or delete likes
+'repo:*'                                       // All collections, all actions
+
+// RPC endpoint access
+'rpc:app.bsky.feed.getTimeline'               // Access to timeline endpoint
+'rpc:app.bsky.feed.*'                         // All feed endpoints
+
+// Blob operations
+'blob:image/*'                                 // Upload images
+'blob:*/*'                                     // Upload any blob type
+
+// Account and identity
+'account:email'                                // Access email
+'identity:handle'                              // Manage handle
+```
+
+## The RequiresScope Attribute
+
+The `#[RequiresScope]` attribute documents and optionally enforces scope requirements on methods.
+
+### Basic Usage
+
+```php
+<?php
+
+namespace App\Atp;
+
+use SocialDept\AtpClient\Attributes\RequiresScope;
+use SocialDept\AtpClient\Client\Requests\Request;
+use SocialDept\AtpClient\Enums\Scope;
+
+class CustomClient extends Request
+{
+    #[RequiresScope(Scope::TransitionGeneric)]
+    public function getTimeline(): array
+    {
+        return $this->atp->client->get('app.bsky.feed.getTimeline')->json();
+    }
+}
+```
+
+### With Granular Scope
+
+Document the future granular scope that will replace the transition scope:
+
+```php
+#[RequiresScope(
+    Scope::TransitionGeneric,
+    granular: 'rpc:app.bsky.feed.getTimeline'
+)]
+public function getTimeline(): GetTimelineResponse
+{
+    // ...
+}
+```
+
+### With Description
+
+Add a human-readable description for documentation:
+
+```php
+#[RequiresScope(
+    Scope::TransitionGeneric,
+    granular: 'rpc:app.bsky.feed.getTimeline',
+    description: 'Access to the user\'s home timeline'
+)]
+public function getTimeline(): GetTimelineResponse
+{
+    // ...
+}
+```
+
+### Multiple Scopes (AND Logic)
+
+When a method requires multiple scopes, all must be present:
+
+```php
+#[RequiresScope([Scope::TransitionGeneric, Scope::TransitionEmail])]
+public function getEmailPreferences(): array
+{
+    // Requires BOTH scopes
+}
+```
+
+### Multiple Attributes (OR Logic)
+
+Use multiple attributes for alternative scope requirements:
+
+```php
+#[RequiresScope(Scope::Atproto)]
+#[RequiresScope(Scope::TransitionGeneric)]
+public function getProfile(string $actor): ProfileViewDetailed
+{
+    // Either scope satisfies the requirement
+}
+```
+
+## Scope Enforcement
+
+### Configuration
+
+Configure scope enforcement in `config/client.php` or via environment variables:
+
+```php
+'scope_enforcement' => ScopeEnforcementLevel::Permissive,
+```
+
+| Level | Behavior |
+|-------|----------|
+| `Strict` | Throws `MissingScopeException` if required scopes are missing |
+| `Permissive` | Logs a warning but attempts the request anyway |
+
+Set via environment variable:
+
+```env
+ATP_SCOPE_ENFORCEMENT=strict
+```
+
+### Programmatic Scope Checking
+
+Check scopes programmatically using the `ScopeChecker`:
+
+```php
+use SocialDept\AtpClient\Auth\ScopeChecker;
+use SocialDept\AtpClient\Facades\Atp;
+
+$checker = app(ScopeChecker::class);
+$session = Atp::as($did)->client->session();
+
+// Check if session has a scope
+if ($checker->hasScope($session, Scope::TransitionGeneric)) {
+    // Session has the scope
+}
+
+// Check multiple scopes
+if ($checker->check($session, [Scope::TransitionGeneric, Scope::TransitionEmail])) {
+    // Session has ALL required scopes
+}
+
+// Check and fail if missing (respects enforcement level)
+$checker->checkOrFail($session, [Scope::TransitionGeneric]);
+
+// Check repo scope for specific action
+if ($checker->checkRepoScope($session, 'app.bsky.feed.post', 'create')) {
+    // Can create posts
+}
+```
+
+### Granular Pattern Matching
+
+The scope checker supports wildcard patterns:
+
+```php
+// Check if session can access any feed endpoint
+$checker->matchesGranular($session, 'rpc:app.bsky.feed.*');
+
+// Check if session can upload images
+$checker->matchesGranular($session, 'blob:image/*');
+
+// Check if session has any repo access
+$checker->matchesGranular($session, 'repo:*');
+```
+
+## Route Middleware
+
+Protect Laravel routes based on ATP session scopes:
+
+```php
+use Illuminate\Support\Facades\Route;
+
+// Single scope
+Route::get('/timeline', TimelineController::class)
+    ->middleware('atp.scope:transition:generic');
+
+// Multiple scopes (AND logic)
+Route::get('/email-settings', EmailSettingsController::class)
+    ->middleware('atp.scope:transition:generic,transition:email');
+```
+
+### Middleware Configuration
+
+Configure middleware behavior in `config/client.php`:
+
+```php
+'scope_authorization' => [
+    // What to do when scope check fails
+    'failure_action' => ScopeAuthorizationFailure::Abort,  // abort, redirect, or exception
+
+    // Where to redirect (when failure_action is 'redirect')
+    'redirect_to' => '/login',
+],
+```
+
+| Failure Action | Behavior |
+|----------------|----------|
+| `Abort` | Returns 403 Forbidden response |
+| `Redirect` | Redirects to configured URL |
+| `Exception` | Throws `ScopeAuthorizationException` |
+
+Set via environment variables:
+
+```env
+ATP_SCOPE_FAILURE_ACTION=redirect
+ATP_SCOPE_REDIRECT=/auth/login
+```
+
+### User Model Integration
+
+For the middleware to work, your User model must implement `HasAtpSession`:
+
+```php
+<?php
+
+namespace App\Models;
+
+use Illuminate\Foundation\Auth\User as Authenticatable;
+use SocialDept\AtpClient\Contracts\HasAtpSession;
+
+class User extends Authenticatable implements HasAtpSession
+{
+    public function getAtpDid(): ?string
+    {
+        return $this->atp_did;
+    }
+}
+```
+
+## Public Mode and Scopes
+
+When using `Atp::public()`, no scope checking occurs because there's no authenticated session:
+
+```php
+// Public mode - no authentication, no scopes
+$client = Atp::public('https://public.api.bsky.app');
+$client->bsky->actor->getProfile('someone.bsky.social');  // Works without scopes
+
+// Authenticated mode - scopes are checked
+$client = Atp::as($did);
+$client->bsky->feed->getTimeline();  // Requires transition:generic scope
+```
+
+Methods that work in public mode typically don't have `#[RequiresScope]` attributes, while authenticated-only methods do.
+
+## Exception Handling
+
+### MissingScopeException
+
+Thrown when required scopes are missing and enforcement is strict:
+
+```php
+use SocialDept\AtpClient\Exceptions\MissingScopeException;
+
+try {
+    $timeline = $client->bsky->feed->getTimeline();
+} catch (MissingScopeException $e) {
+    $missing = $e->getMissingScopes();   // Scopes that are missing
+    $granted = $e->getGrantedScopes();   // Scopes the session has
+
+    // Handle missing scope
+}
+```
+
+### ScopeAuthorizationException
+
+Thrown by middleware when route access is denied:
+
+```php
+use SocialDept\AtpClient\Exceptions\ScopeAuthorizationException;
+
+try {
+    // Route protected by atp.scope middleware
+} catch (ScopeAuthorizationException $e) {
+    $required = $e->getRequiredScopes();
+    $granted = $e->getGrantedScopes();
+    $message = $e->getMessage();
+}
+```
+
+## Best Practices
+
+### 1. Document All Scope Requirements
+
+Always add `#[RequiresScope]` to methods that require authentication:
+
+```php
+#[RequiresScope(
+    Scope::TransitionGeneric,
+    granular: 'rpc:app.bsky.feed.getTimeline',
+    description: 'Fetches the authenticated user\'s home timeline'
+)]
+public function getTimeline(): GetTimelineResponse
+```
+
+### 2. Use the Scope Enum
+
+Prefer the `Scope` enum over string literals for type safety:
+
+```php
+// Good
+#[RequiresScope(Scope::TransitionGeneric)]
+
+// Avoid
+#[RequiresScope('transition:generic')]
+```
+
+### 3. Request Minimal Scopes
+
+When implementing OAuth, request only the scopes your application needs:
+
+```php
+$authUrl = Atp::oauth()->getAuthorizationUrl([
+    'scope' => 'atproto transition:generic',
+]);
+```
+
+### 4. Handle Missing Scopes Gracefully
+
+Check for scope availability before attempting operations:
+
+```php
+$checker = app(ScopeChecker::class);
+$session = $client->client->session();
+
+if ($checker->hasScope($session, Scope::TransitionChat)) {
+    $conversations = $client->chat->getConversations();
+} else {
+    // Inform user they need to re-authorize with chat scope
+}
+```
+
+### 5. Use Permissive Mode in Development
+
+Start with permissive enforcement during development, then switch to strict for production:
+
+```env
+# .env.local
+ATP_SCOPE_ENFORCEMENT=permissive
+
+# .env.production
+ATP_SCOPE_ENFORCEMENT=strict
+```