docs: consolidate documentation into organized structure

- Move 12 markdown files from root to docs/ subdirectories
- Organize documentation by category:
  • docs/troubleshooting/ (1 file)  - Technical troubleshooting guides
  • docs/deployment/      (4 files) - Deployment and security documentation
  • docs/guides/          (3 files) - Feature-specific guides
  • docs/planning/        (4 files) - Planning and improvement proposals

Root directory cleanup:
- Reduced from 16 to 4 markdown files in root
- Only essential project files remain:
  • CLAUDE.md (AI instructions)
  • README.md (Main project readme)
  • CLEANUP_PLAN.md (Current cleanup plan)
  • SRC_STRUCTURE_IMPROVEMENTS.md (Structure improvements)

This improves:
✅ Documentation discoverability
✅ Logical organization by purpose
✅ Clean root directory
✅ Better maintainability

src/Framework/OAuth/ValueObjects/TokenScope.php

@@ -0,0 +1,145 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Framework\OAuth\ValueObjects;
+
+/**
+ * OAuth Token Scope Value Object
+ *
+ * Represents OAuth scopes (space-separated as per RFC 6749)
+ */
+final readonly class TokenScope
+{
+    /**
+     * @param array<string> $scopes
+     */
+    public function __construct(
+        private array $scopes,
+    ) {
+        if (empty($scopes)) {
+            throw new \InvalidArgumentException('Token scope cannot be empty');
+        }
+
+        foreach ($scopes as $scope) {
+            if (!is_string($scope) || empty(trim($scope))) {
+                throw new \InvalidArgumentException('Invalid scope value');
+            }
+        }
+    }
+
+    /**
+     * Create from space-separated string (OAuth standard format)
+     */
+    public static function fromString(string $scopeString): self
+    {
+        $scopes = array_filter(
+            array_map('trim', explode(' ', $scopeString)),
+            fn($scope) => !empty($scope)
+        );
+
+        return new self($scopes);
+    }
+
+    /**
+     * Create from array of scopes
+     *
+     * @param array<string> $scopes
+     */
+    public static function fromArray(array $scopes): self
+    {
+        return new self($scopes);
+    }
+
+    /**
+     * Get scopes as array
+     *
+     * @return array<string>
+     */
+    public function toArray(): array
+    {
+        return $this->scopes;
+    }
+
+    /**
+     * Get scopes as space-separated string (OAuth standard format)
+     */
+    public function toString(): string
+    {
+        return implode(' ', $this->scopes);
+    }
+
+    /**
+     * Check if scope includes a specific permission
+     */
+    public function includes(string $scope): bool
+    {
+        return in_array($scope, $this->scopes, true);
+    }
+
+    /**
+     * Check if scope includes all specified permissions
+     *
+     * @param array<string> $requiredScopes
+     */
+    public function includesAll(array $requiredScopes): bool
+    {
+        foreach ($requiredScopes as $required) {
+            if (!$this->includes($required)) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    /**
+     * Check if scope includes any of the specified permissions
+     *
+     * @param array<string> $scopes
+     */
+    public function includesAny(array $scopes): bool
+    {
+        foreach ($scopes as $scope) {
+            if ($this->includes($scope)) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    /**
+     * Add additional scopes
+     *
+     * @param array<string> $additionalScopes
+     */
+    public function withAdditional(array $additionalScopes): self
+    {
+        return new self([...$this->scopes, ...$additionalScopes]);
+    }
+
+    /**
+     * Remove specific scopes
+     *
+     * @param array<string> $scopesToRemove
+     */
+    public function without(array $scopesToRemove): self
+    {
+        $filtered = array_filter(
+            $this->scopes,
+            fn($scope) => !in_array($scope, $scopesToRemove, true)
+        );
+
+        if (empty($filtered)) {
+            throw new \InvalidArgumentException('Cannot remove all scopes');
+        }
+
+        return new self(array_values($filtered));
+    }
+
+    public function __toString(): string
+    {
+        return $this->toString();
+    }
+}