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/Metrics/Counter.php

@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Framework\Metrics;
+
+/**
+ * Immutable counter value object
+ * Represents a single named counter with its current value
+ */
+final readonly class Counter
+{
+    public function __construct(
+        public string $name,
+        public int $value = 0
+    ) {
+    }
+
+    public function increment(int $by = 1): self
+    {
+        return new self($this->name, $this->value + $by);
+    }
+
+    public function reset(): self
+    {
+        return new self($this->name, 0);
+    }
+
+    public function withValue(int $value): self
+    {
+        return new self($this->name, $value);
+    }
+}

src/Framework/Metrics/FrameworkCounters.php

@@ -0,0 +1,92 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Framework\Metrics;
+
+/**
+ * Immutable registry of Counter value objects
+ * Framework-internal counters without Prometheus overhead
+ */
+final readonly class FrameworkCounters
+{
+    /**
+     * @param array<string, Counter> $counters
+     */
+    public function __construct(
+        private array $counters = []
+    ) {
+    }
+
+    public function get(string $name): Counter
+    {
+        return $this->counters[$name] ?? new Counter($name, 0);
+    }
+
+    public function increment(string $name, int $by = 1): self
+    {
+        $current = $this->get($name);
+        $updated = $current->increment($by);
+
+        return new self([
+            ...$this->counters,
+            $name => $updated,
+        ]);
+    }
+
+    public function reset(string $name): self
+    {
+        $current = $this->get($name);
+        $updated = $current->reset();
+
+        return new self([
+            ...$this->counters,
+            $name => $updated,
+        ]);
+    }
+
+    public function resetAll(): self
+    {
+        return new self([]);
+    }
+
+    /**
+     * Get all counters
+     * @return array<string, Counter>
+     */
+    public function all(): array
+    {
+        return $this->counters;
+    }
+
+    /**
+     * Convert to simple array for serialization
+     * @return array<string, int>
+     */
+    public function toArray(): array
+    {
+        return array_map(
+            fn (Counter $counter) => $counter->value,
+            $this->counters
+        );
+    }
+
+    /**
+     * Export counters as MetricsCollection for Prometheus compatibility
+     */
+    public function toMetricsCollection(): MetricsCollection
+    {
+        $collection = new MetricsCollection();
+
+        foreach ($this->counters as $counter) {
+            $collection->counter(
+                name: "framework_{$counter->name}",
+                value: (float) $counter->value,
+                help: "Framework internal counter: {$counter->name}",
+                labels: ['type' => 'internal']
+            );
+        }
+
+        return $collection;
+    }
+}

src/Framework/Metrics/FrameworkMetricsCollector.php

@@ -0,0 +1,52 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Framework\Metrics;
+
+/**
+ * Mutable service for collecting framework-internal counters
+ * Wraps immutable FrameworkCounters for DI compatibility
+ */
+final class FrameworkMetricsCollector
+{
+    private FrameworkCounters $counters;
+
+    public function __construct()
+    {
+        $this->counters = new FrameworkCounters();
+    }
+
+    public function increment(string $name, int $by = 1): void
+    {
+        $this->counters = $this->counters->increment($name, $by);
+    }
+
+    public function reset(string $name): void
+    {
+        $this->counters = $this->counters->reset($name);
+    }
+
+    public function resetAll(): void
+    {
+        $this->counters = $this->counters->resetAll();
+    }
+
+    public function get(string $name): Counter
+    {
+        return $this->counters->get($name);
+    }
+
+    public function snapshot(): FrameworkCounters
+    {
+        return $this->counters;
+    }
+
+    /**
+     * Export framework counters as MetricsCollection
+     */
+    public function collect(): MetricsCollection
+    {
+        return $this->counters->toMetricsCollection();
+    }
+}