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/Admin/FormFields/Fields/CheckboxField.php

@@ -0,0 +1,106 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Framework\Admin\FormFields\Fields;
+
+use App\Framework\Admin\FormFields\FormField;
+use App\Framework\Admin\FormFields\ValueObjects\FieldAttributes;
+use App\Framework\Admin\FormFields\ValueObjects\FieldMetadata;
+use App\Framework\Admin\FormFields\Components\FieldWrapper;
+use App\Framework\View\FormBuilder;
+use App\Framework\View\ValueObjects\FormElement;
+
+/**
+ * Checkbox Field
+ *
+ * Single checkbox input field using composition
+ */
+final readonly class CheckboxField implements FormField
+{
+    public function __construct(
+        private FieldMetadata $metadata,
+        private FieldAttributes $attributes,
+        private FieldWrapper $wrapper,
+        private mixed $value = null,
+        private string $checkedValue = '1'
+    ) {}
+
+    public static function create(
+        string $name,
+        string $label,
+        mixed $value = null,
+        bool $required = false,
+        ?string $help = null,
+        string $checkedValue = '1'
+    ): self {
+        return new self(
+            metadata: new FieldMetadata($name, $label, $help),
+            attributes: new FieldAttributes(
+                name: $name,
+                id: $name,
+                class: 'form-check-input',
+                required: $required
+            ),
+            wrapper: new FieldWrapper(),
+            value: $value,
+            checkedValue: $checkedValue
+        );
+    }
+
+    public function render(FormBuilder $form): FormBuilder
+    {
+        $attrs = $this->attributes->withAdditional(['type' => 'checkbox', 'value' => $this->checkedValue]);
+        $attrArray = $attrs->toArray();
+
+        if ($this->isChecked()) {
+            $attrArray['checked'] = 'checked';
+        }
+
+        $input = FormElement::create('input', $attrArray);
+
+        $label = FormElement::create(
+            'label',
+            ['class' => 'form-check-label', 'for' => $this->metadata->name],
+            $this->metadata->label
+        );
+
+        $checkboxHtml = FormElement::create(
+            'div',
+            ['class' => 'form-check'],
+            $input . $label
+        );
+
+        $wrapped = $this->wrapper->wrapWithoutLabel($checkboxHtml, $this->metadata);
+
+        return $form->addElement($wrapped);
+    }
+
+    public function getName(): string
+    {
+        return $this->metadata->name;
+    }
+
+    public function getValue(): mixed
+    {
+        return $this->value;
+    }
+
+    public function getLabel(): string
+    {
+        return $this->metadata->label;
+    }
+
+    private function isChecked(): bool
+    {
+        if ($this->value === null) {
+            return false;
+        }
+
+        if (is_bool($this->value)) {
+            return $this->value;
+        }
+
+        return (string) $this->value === $this->checkedValue;
+    }
+}

src/Framework/Admin/FormFields/Fields/DateTimeField.php

@@ -0,0 +1,105 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Framework\Admin\FormFields\Fields;
+
+use App\Framework\Admin\FormFields\FormField;
+use App\Framework\Admin\FormFields\ValueObjects\FieldAttributes;
+use App\Framework\Admin\FormFields\ValueObjects\FieldMetadata;
+use App\Framework\Admin\FormFields\Components\FieldWrapper;
+use App\Framework\View\FormBuilder;
+use App\Framework\View\ValueObjects\FormElement;
+use DateTimeInterface;
+
+/**
+ * DateTime Input Field
+ *
+ * DateTime input field with formatting using composition
+ */
+final readonly class DateTimeField implements FormField
+{
+    public function __construct(
+        private FieldMetadata $metadata,
+        private FieldAttributes $attributes,
+        private FieldWrapper $wrapper,
+        private mixed $value = null,
+        private string $type = 'datetime-local'
+    ) {}
+
+    public static function create(
+        string $name,
+        string $label,
+        mixed $value = null,
+        bool $required = false,
+        ?string $help = null,
+        string $type = 'datetime-local'
+    ): self {
+        return new self(
+            metadata: new FieldMetadata($name, $label, $help),
+            attributes: new FieldAttributes(
+                name: $name,
+                id: $name,
+                required: $required
+            ),
+            wrapper: new FieldWrapper(),
+            value: $value,
+            type: $type
+        );
+    }
+
+    public function render(FormBuilder $form): FormBuilder
+    {
+        $attrs = $this->attributes->withAdditional(['type' => $this->type]);
+        $attrArray = $attrs->toArray();
+
+        if ($this->value !== null) {
+            $attrArray['value'] = $this->formatValue($this->value);
+        }
+
+        $input = FormElement::create('input', $attrArray);
+        $wrapped = $this->wrapper->wrap($input, $this->metadata);
+
+        return $form->addElement($wrapped);
+    }
+
+    public function getName(): string
+    {
+        return $this->metadata->name;
+    }
+
+    public function getValue(): mixed
+    {
+        return $this->value;
+    }
+
+    public function getLabel(): string
+    {
+        return $this->metadata->label;
+    }
+
+    private function formatValue(mixed $value): string
+    {
+        if ($value instanceof DateTimeInterface) {
+            return $value->format($this->getFormatForType());
+        }
+
+        if (is_string($value) && strtotime($value) !== false) {
+            return date($this->getFormatForType(), strtotime($value));
+        }
+
+        return (string) $value;
+    }
+
+    private function getFormatForType(): string
+    {
+        return match ($this->type) {
+            'date' => 'Y-m-d',
+            'time' => 'H:i',
+            'datetime-local' => 'Y-m-d\TH:i',
+            'month' => 'Y-m',
+            'week' => 'Y-\WW',
+            default => 'Y-m-d\TH:i'
+        };
+    }
+}

src/Framework/Admin/FormFields/Fields/EmailField.php

@@ -0,0 +1,78 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Framework\Admin\FormFields\Fields;
+
+use App\Framework\Admin\FormFields\FormField;
+use App\Framework\Admin\FormFields\ValueObjects\FieldAttributes;
+use App\Framework\Admin\FormFields\ValueObjects\FieldMetadata;
+use App\Framework\Admin\FormFields\Components\FieldWrapper;
+use App\Framework\View\FormBuilder;
+use App\Framework\View\ValueObjects\FormElement;
+
+/**
+ * Email Input Field
+ *
+ * Email input field with validation using composition
+ */
+final readonly class EmailField implements FormField
+{
+    public function __construct(
+        private FieldMetadata $metadata,
+        private FieldAttributes $attributes,
+        private FieldWrapper $wrapper,
+        private mixed $value = null
+    ) {}
+
+    public static function create(
+        string $name,
+        string $label,
+        mixed $value = null,
+        bool $required = false,
+        ?string $placeholder = null,
+        ?string $help = null
+    ): self {
+        return new self(
+            metadata: new FieldMetadata($name, $label, $help),
+            attributes: new FieldAttributes(
+                name: $name,
+                id: $name,
+                required: $required,
+                placeholder: $placeholder
+            ),
+            wrapper: new FieldWrapper(),
+            value: $value
+        );
+    }
+
+    public function render(FormBuilder $form): FormBuilder
+    {
+        $attrs = $this->attributes->withAdditional(['type' => 'email']);
+        $attrArray = $attrs->toArray();
+
+        if ($this->value !== null && $this->value !== '') {
+            $attrArray['value'] = (string) $this->value;
+        }
+
+        $input = FormElement::create('input', $attrArray);
+        $wrapped = $this->wrapper->wrap($input, $this->metadata);
+
+        return $form->addElement($wrapped);
+    }
+
+    public function getName(): string
+    {
+        return $this->metadata->name;
+    }
+
+    public function getValue(): mixed
+    {
+        return $this->value;
+    }
+
+    public function getLabel(): string
+    {
+        return $this->metadata->label;
+    }
+}

src/Framework/Admin/FormFields/Fields/HiddenField.php

@@ -0,0 +1,74 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Framework\Admin\FormFields\Fields;
+
+use App\Framework\Admin\FormFields\FormField;
+use App\Framework\Admin\FormFields\ValueObjects\FieldAttributes;
+use App\Framework\Admin\FormFields\ValueObjects\FieldMetadata;
+use App\Framework\View\FormBuilder;
+use App\Framework\View\ValueObjects\FormElement;
+
+/**
+ * Hidden Input Field
+ *
+ * Hidden input field using composition (no wrapper needed)
+ */
+final readonly class HiddenField implements FormField
+{
+    public function __construct(
+        private FieldMetadata $metadata,
+        private FieldAttributes $attributes,
+        private mixed $value = null
+    ) {}
+
+    public static function create(
+        string $name,
+        mixed $value = null
+    ): self {
+        return new self(
+            metadata: new FieldMetadata($name, ''),
+            attributes: new FieldAttributes(
+                name: $name,
+                id: $name,
+                class: ''
+            ),
+            value: $value
+        );
+    }
+
+    public function render(FormBuilder $form): FormBuilder
+    {
+        $attrs = $this->attributes->withAdditional(['type' => 'hidden']);
+        $attrArray = $attrs->toArray();
+
+        // Remove empty class attribute for hidden fields
+        if (empty($attrArray['class'])) {
+            unset($attrArray['class']);
+        }
+
+        if ($this->value !== null && $this->value !== '') {
+            $attrArray['value'] = (string) $this->value;
+        }
+
+        $input = FormElement::create('input', $attrArray);
+
+        return $form->addElement($input);
+    }
+
+    public function getName(): string
+    {
+        return $this->metadata->name;
+    }
+
+    public function getValue(): mixed
+    {
+        return $this->value;
+    }
+
+    public function getLabel(): string
+    {
+        return $this->metadata->label;
+    }
+}

src/Framework/Admin/FormFields/Fields/NumberField.php

@@ -0,0 +1,101 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Framework\Admin\FormFields\Fields;
+
+use App\Framework\Admin\FormFields\FormField;
+use App\Framework\Admin\FormFields\ValueObjects\FieldAttributes;
+use App\Framework\Admin\FormFields\ValueObjects\FieldMetadata;
+use App\Framework\Admin\FormFields\Components\FieldWrapper;
+use App\Framework\View\FormBuilder;
+use App\Framework\View\ValueObjects\FormElement;
+
+/**
+ * Number Input Field
+ *
+ * Number input field with min/max/step using composition
+ */
+final readonly class NumberField implements FormField
+{
+    public function __construct(
+        private FieldMetadata $metadata,
+        private FieldAttributes $attributes,
+        private FieldWrapper $wrapper,
+        private mixed $value = null,
+        private ?int $min = null,
+        private ?int $max = null,
+        private ?int $step = null
+    ) {}
+
+    public static function create(
+        string $name,
+        string $label,
+        mixed $value = null,
+        bool $required = false,
+        ?string $placeholder = null,
+        ?string $help = null,
+        ?int $min = null,
+        ?int $max = null,
+        ?int $step = null
+    ): self {
+        return new self(
+            metadata: new FieldMetadata($name, $label, $help),
+            attributes: new FieldAttributes(
+                name: $name,
+                id: $name,
+                required: $required,
+                placeholder: $placeholder
+            ),
+            wrapper: new FieldWrapper(),
+            value: $value,
+            min: $min,
+            max: $max,
+            step: $step
+        );
+    }
+
+    public function render(FormBuilder $form): FormBuilder
+    {
+        $additionalAttrs = ['type' => 'number'];
+
+        if ($this->min !== null) {
+            $additionalAttrs['min'] = (string) $this->min;
+        }
+
+        if ($this->max !== null) {
+            $additionalAttrs['max'] = (string) $this->max;
+        }
+
+        if ($this->step !== null) {
+            $additionalAttrs['step'] = (string) $this->step;
+        }
+
+        $attrs = $this->attributes->withAdditional($additionalAttrs);
+        $attrArray = $attrs->toArray();
+
+        if ($this->value !== null && $this->value !== '') {
+            $attrArray['value'] = (string) $this->value;
+        }
+
+        $input = FormElement::create('input', $attrArray);
+        $wrapped = $this->wrapper->wrap($input, $this->metadata);
+
+        return $form->addElement($wrapped);
+    }
+
+    public function getName(): string
+    {
+        return $this->metadata->name;
+    }
+
+    public function getValue(): mixed
+    {
+        return $this->value;
+    }
+
+    public function getLabel(): string
+    {
+        return $this->metadata->label;
+    }
+}

src/Framework/Admin/FormFields/Fields/SelectField.php

@@ -0,0 +1,78 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Framework\Admin\FormFields\Fields;
+
+use App\Framework\Admin\FormFields\FormField;
+use App\Framework\Admin\FormFields\ValueObjects\FieldAttributes;
+use App\Framework\Admin\FormFields\ValueObjects\FieldMetadata;
+use App\Framework\Admin\FormFields\ValueObjects\FieldOptions;
+use App\Framework\Admin\FormFields\Components\FieldWrapper;
+use App\Framework\View\FormBuilder;
+use App\Framework\View\ValueObjects\FormElement;
+
+/**
+ * Select Dropdown Field
+ *
+ * Select field with options using composition
+ */
+final readonly class SelectField implements FormField
+{
+    public function __construct(
+        private FieldMetadata $metadata,
+        private FieldAttributes $attributes,
+        private FieldWrapper $wrapper,
+        private FieldOptions $options,
+        private mixed $value = null
+    ) {}
+
+    public static function create(
+        string $name,
+        string $label,
+        array $options,
+        mixed $value = null,
+        bool $required = false,
+        ?string $help = null,
+        ?string $placeholder = null
+    ): self {
+        return new self(
+            metadata: new FieldMetadata($name, $label, $help),
+            attributes: new FieldAttributes(
+                name: $name,
+                id: $name,
+                required: $required
+            ),
+            wrapper: new FieldWrapper(),
+            options: new FieldOptions($options, $placeholder),
+            value: $value
+        );
+    }
+
+    public function render(FormBuilder $form): FormBuilder
+    {
+        $attrArray = $this->attributes->toArray();
+
+        $optionsHtml = $this->options->toHtml((string) $this->value);
+
+        $select = FormElement::create('select', $attrArray, $optionsHtml);
+        $wrapped = $this->wrapper->wrap($select, $this->metadata);
+
+        return $form->addElement($wrapped);
+    }
+
+    public function getName(): string
+    {
+        return $this->metadata->name;
+    }
+
+    public function getValue(): mixed
+    {
+        return $this->value;
+    }
+
+    public function getLabel(): string
+    {
+        return $this->metadata->label;
+    }
+}

src/Framework/Admin/FormFields/Fields/TextField.php

@@ -0,0 +1,79 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Framework\Admin\FormFields\Fields;
+
+use App\Framework\Admin\FormFields\FormField;
+use App\Framework\Admin\FormFields\ValueObjects\FieldAttributes;
+use App\Framework\Admin\FormFields\ValueObjects\FieldMetadata;
+use App\Framework\Admin\FormFields\Components\FieldWrapper;
+use App\Framework\View\FormBuilder;
+use App\Framework\View\ValueObjects\FormElement;
+
+/**
+ * Text Input Field
+ *
+ * Standard text input field using composition
+ */
+final readonly class TextField implements FormField
+{
+    public function __construct(
+        private FieldMetadata $metadata,
+        private FieldAttributes $attributes,
+        private FieldWrapper $wrapper,
+        private mixed $value = null
+    ) {}
+
+    public static function create(
+        string $name,
+        string $label,
+        mixed $value = null,
+        bool $required = false,
+        ?string $placeholder = null,
+        ?string $help = null
+    ): self {
+        return new self(
+            metadata: new FieldMetadata($name, $label, $help),
+            attributes: new FieldAttributes(
+                name: $name,
+                id: $name,
+                required: $required,
+                placeholder: $placeholder
+            ),
+            wrapper: new FieldWrapper(),
+            value: $value
+        );
+    }
+
+    public function render(FormBuilder $form): FormBuilder
+    {
+        $attrs = $this->attributes->withAdditional(['type' => 'text']);
+
+        $attrArray = $attrs->toArray();
+
+        if ($this->value !== null && $this->value !== '') {
+            $attrArray['value'] = (string) $this->value;
+        }
+
+        $input = FormElement::create('input', $attrArray);
+        $wrapped = $this->wrapper->wrap($input, $this->metadata);
+
+        return $form->addElement($wrapped);
+    }
+
+    public function getName(): string
+    {
+        return $this->metadata->name;
+    }
+
+    public function getValue(): mixed
+    {
+        return $this->value;
+    }
+
+    public function getLabel(): string
+    {
+        return $this->metadata->label;
+    }
+}

src/Framework/Admin/FormFields/Fields/TextareaField.php

@@ -0,0 +1,79 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Framework\Admin\FormFields\Fields;
+
+use App\Framework\Admin\FormFields\FormField;
+use App\Framework\Admin\FormFields\ValueObjects\FieldAttributes;
+use App\Framework\Admin\FormFields\ValueObjects\FieldMetadata;
+use App\Framework\Admin\FormFields\Components\FieldWrapper;
+use App\Framework\View\FormBuilder;
+use App\Framework\View\ValueObjects\FormElement;
+
+/**
+ * Textarea Field
+ *
+ * Multi-line text input field using composition
+ */
+final readonly class TextareaField implements FormField
+{
+    public function __construct(
+        private FieldMetadata $metadata,
+        private FieldAttributes $attributes,
+        private FieldWrapper $wrapper,
+        private mixed $value = null,
+        private int $rows = 5
+    ) {}
+
+    public static function create(
+        string $name,
+        string $label,
+        mixed $value = null,
+        bool $required = false,
+        ?string $placeholder = null,
+        ?string $help = null,
+        int $rows = 5
+    ): self {
+        return new self(
+            metadata: new FieldMetadata($name, $label, $help),
+            attributes: new FieldAttributes(
+                name: $name,
+                id: $name,
+                required: $required,
+                placeholder: $placeholder
+            ),
+            wrapper: new FieldWrapper(),
+            value: $value,
+            rows: $rows
+        );
+    }
+
+    public function render(FormBuilder $form): FormBuilder
+    {
+        $attrs = $this->attributes->withAdditional(['rows' => (string) $this->rows]);
+        $attrArray = $attrs->toArray();
+
+        $content = $this->value !== null ? htmlspecialchars((string) $this->value) : '';
+
+        $textarea = FormElement::create('textarea', $attrArray, $content);
+        $wrapped = $this->wrapper->wrap($textarea, $this->metadata);
+
+        return $form->addElement($wrapped);
+    }
+
+    public function getName(): string
+    {
+        return $this->metadata->name;
+    }
+
+    public function getValue(): mixed
+    {
+        return $this->value;
+    }
+
+    public function getLabel(): string
+    {
+        return $this->metadata->label;
+    }
+}