update after stop build

vendor/knuckleswtf/scribe/AGENTS.md

@@ -0,0 +1,82 @@
+# Agent Guidelines for Scribe
+
+This repository contains the source code for Scribe, a PHP package that generates API documentation for Laravel applications.
+
+## 🛠 Project Tooling & Commands
+
+This project uses **Composer** for dependency management and scripts.
+- **Test Runner**: [Pest](https://pestphp.com/) (which wraps PHPUnit).
+- **Static Analysis**: [PHPStan](https://phpstan.org/).
+- **Code Style**: [PHP-CS-Fixer](https://cs.symfony.com/).
+
+### Key Commands
+
+| Action | Command | Description |
+|--------|---------|-------------|
+| **Run Tests** | `composer test` | Runs all tests using Pest. |
+| **Run Single Test** | `vendor/bin/pest --filter MethodName` | Runs a specific test method. |
+| **Run File Tests** | `vendor/bin/pest path/to/Test.php` | Runs all tests in a specific file. |
+| **Lint Code** | `composer lint` | Runs PHPStan analysis. |
+| **Check Style** | `composer style:check` | Checks code style without modifying files. |
+| **Fix Style** | `composer style:fix` | Automatically fixes code style issues. |
+
+> **Note**: Always run `composer test` and `composer lint` before submitting changes.
+
+## 📐 Code Style & Conventions
+
+Adhere strictly to the existing style. The project generally follows **PSR-12**.
+
+### General PHP
+- **Version**: PHP 8.1+. Use modern features like typed properties, union types, and constructor promotion where appropriate.
+- **Strict Types**: Do **NOT** use `declare(strict_types=1);` unless strictly necessary or found in the file being edited (it is generally absent).
+- **Indentation**: 4 spaces.
+- **Arrays**: Use short array syntax `[]`.
+- **Trailing Commas**: Use trailing commas in multi-line arrays.
+
+### Naming
+- **Classes**: `PascalCase` (e.g., `PostmanCollectionWriter`).
+- **Methods**: `camelCase` (e.g., `generatePostmanCollection`).
+- **Variables**: `camelCase` (e.g., `$groupedEndpoints`).
+- **Constants**: `UPPER_CASE_WITH_UNDERSCORES`.
+
+### Imports & Namespaces
+- **Ordering**: Alphabetical order.
+- **Grouping**: Group standard library imports separately if applicable, but generally keep them sorted.
+- **Unused Imports**: Remove unused imports.
+
+### Type Hinting & Docblocks
+- **Types**: Use native PHP type hints (param and return types) whenever possible.
+    - Example: `public function writeDocs(array $groupedEndpoints): void`
+- **Docblocks**:
+    - Use PHPDoc for generic arrays to specify content types (e.g., `/** @param array<string, mixed> $config */`).
+    - Use `/** @var ClassName $var */` for inline type hinting when the static analyzer cannot infer it (e.g., resolving from container).
+    - Do not duplicate native type info in docblocks unless adding detail.
+
+### Laravel Integration
+- **Dependency Injection**: Prefer constructor injection.
+- **Helpers**: Use Laravel helpers (`app()`, `config()`, `public_path()`) where appropriate and consistent with existing code.
+- **Facades**: Facades are used (e.g., `Storage`, `Route`). Import them via `Illuminate\Support\Facades\...`.
+
+## 🧪 Testing Guidelines
+
+- **Framework**: Tests are written using PHPUnit class syntax (extending `BaseLaravelTest` or `TestCase`), but executed via Pest.
+- **Location**: Place unit tests in `tests/Unit/`.
+- **Naming**: Test classes end in `Test.php`. Test methods use the `/** @test */` annotation or start with `test`.
+- **Assertions**: Use standard PHPUnit assertions (e.g., `$this->assertEquals`, `$this->assertCount`).
+- **Mocking**: Use Mockery or Laravel's mocking helpers if applicable.
+
+## 📂 File Structure
+
+- `src/`: Core package source code.
+    - `Writing/`: Logic for generating output files (HTML, Postman, OpenAPI).
+    - `Tools/`: Utility classes.
+    - `Attributes/`: PHP Attributes used by the package.
+- `tests/`: Test suite.
+- `resources/views/`: Blade templates for generated documentation.
+- `config/`: Configuration files.
+
+## 📝 Error Handling
+
+- Use specific exceptions where possible (e.g., `ScribeException`).
+- Handle errors gracefully, especially when parsing user code or configuration.
+- Use `ConsoleOutputUtils` (aliased as `c`) for CLI output in commands.