Documentation added

AGENTS.md

@@ -0,0 +1,19 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+Source code lives under `src/`, with `ComposerPlugin.php` bootstrapping the Composer integration and the `Commands/` directory holding the WP-CLI subcommands (`MakePotCommand`, `MakeJsonCommand`, etc.). Shared helpers such as `ShellRunner.php` and `I18nConfig.php` sit at the root of `src/` for reuse. Tests live in `tests/Commands` and mirror the command class names. Composer metadata (`composer.json`, `phpstan.neon.dist`, `phpunit.xml.dist`) resides at the project root; avoid editing `vendor/` manually.
+
+## Build, Test, and Development Commands
+Run `composer install` after cloning to pull dependencies and register the plugin. Use `composer qa` for the quick pre-flight check (PHPCS with WPCS ruleset plus PHPStan level 10). Execute `composer tests` for the PHPUnit suite, and `composer tests:coverage` when you need HTML coverage output in `tests/coverage/`. Fix formatting automatically with `composer cs:fix`.
+
+## Coding Style & Naming Conventions
+We target PHP 7.4+ and follow PSR-4 autoloading (`lloc\ComposerI18nScripts\` namespace). Adopt the WordPress Coding Standards with four-space indentation, snake_case function names when calling WP APIs, and StudlyCase class names that end with `Command` for WP-CLI handlers. Mirror class names in file names, and keep configuration arrays ordered consistently to aid PHPStan. Before committing, run `composer cs` to confirm a clean lint baseline.
+
+## Testing Guidelines
+Cover new functionality with PHPUnit tests under `tests/Commands`, using the `*Test` suffix. When introducing a command or helper, add the companion test class and describe edge cases. Prefer data providers for repetitive scenarios and assert exit codes plus generated file paths. Run `composer tests` before pushing; if you alter CLI output or file generation, assert on the rendered strings or fixtures. Keep the coverage directory out of version control.
+
+## Commit & Pull Request Guidelines
+Commit messages are short, present-tense imperatives (`Add MakePot command`, `Raise PHPStan level`). Squash noisy fix-ups locally. Each pull request should include a concise summary, linked GitHub issues (`Fixes #123`), notable commands you ran, and screenshots or sample output when altering CLI behaviour. Mention whether documentation in `README.md` or this guide needs updates.
+
+## Localization Workflow Tips
+Command classes convert translation templates into multiple formats; leverage existing helpers (`ShellRunner`) instead of spawning custom shell logic. When adding options, document them in the command’s PHPDoc and update related tests to cover both WP-CLI arguments and generated artifacts. Validate that generated `.pot` and `.json` files respect WordPress locale conventions to keep downstream usage smooth.

README.md

@@ -1,4 +1,63 @@
 # Composer i18n Scripts
 
-Simplify the internationalization of your WordPress plugin or theme using WP-CLI — powered by Composer.
+Automate the internationalization workflow of your WordPress plugin or theme by wiring WP-CLI translation tools into familiar Composer commands.
 
+## Requirements
+- PHP 7.4+ and Composer 2.6+ (Composer plugin API 2.6 is required)
+- WP-CLI 2.12+ available on your `$PATH`
+- A WordPress plugin or theme with `Text Domain` and `Domain Path` headers defined
+
+## Installation
+```bash
+composer require --dev lloc/composer-i18n-scripts
+```
+Composer automatically registers the plugin; no manual bootstrap code is needed. Running `composer install` on the project will keep the plugin active for all contributors.
+
+## Configuration
+The plugin inspects your project root to infer settings:
+- Themes: reads `style.css`
+- Plugins: reads the main plugin file (matching the directory name or `index.php`)
+
+Provide headers like the following so WP-CLI receives the right text domain and language directory:
+```php
+/*
+Plugin Name: Sample Plugin
+Text Domain: sample-plugin
+Domain Path: /languages
+*/
+```
+If no metadata is found, defaults are `Text Domain: messages` and `Domain Path: /languages`.
+
+## Usage
+Run the commands from the WordPress project root so that `wp` can load your environment.
+
+| Command | Purpose |
+| ------- | ------- |
+| `composer i18n:make-pot` | Scan the source directory and generate `languages/<domain>.pot`. |
+| `composer i18n:create-po <locale>` | Copy the `.pot` file to a locale-specific `.po` file (e.g. `de_DE`). |
+| `composer i18n:update-po` | Merge the current `.pot` changes into every `.po` in `languages/`. |
+| `composer i18n:make-mo` | Compile all `.po` files into `.mo` binaries. |
+| `composer i18n:make-php` | Export `.po` translations into PHP array files for performance-sensitive setups. |
+| `composer i18n:make-json` | Build JavaScript translation catalogs (`*.json`) without purging existing assets. |
+
+Example workflow:
+```bash
+composer i18n:make-pot
+composer i18n:update-po
+composer i18n:make-json
+composer i18n:make-mo
+```
+
+## Development
+- `composer install` – install dependencies and register the plugin
+- `composer qa` – PHPCS (WordPress Coding Standards) + PHPStan level 10
+- `composer tests` – run PHPUnit suite under `tests/Commands`
+- `composer tests:coverage` – generate HTML coverage in `tests/coverage/`
+- `composer cs:fix` – automatically fix style violations
+
+Refer to `AGENTS.md` for contributor conventions, coding standards, and pull request expectations.
+
+## Troubleshooting
+- **“Text domain is not set”**: ensure your plugin/theme headers declare `Text Domain` and `Domain Path`.
+- **WP-CLI not found**: verify `wp` is installed globally or provide an absolute path (e.g. symlink `wp` into `/usr/local/bin`).
+- **Translations not picking up new strings**: rerun `composer i18n:make-pot` before updating `.po` files so the template is up to date.