chore(release): prepare 1.2.2

.claude/commands/README.md

@@ -1,18 +1,16 @@
 # Claude Commands
 
-Custom command definitions for repository-specific tasks can be added here.
+Repository-specific command playbooks for Claude workflows.
 
-## Current Status
+## Available Commands
 
-No custom command files are committed yet.
+- `quality-check.md`: final validation flow for code changes.
+- `docs-verify.md`: markdown-link and docs-structure verification.
+- `release-readiness.md`: release preflight checks.
 
-## Recommended Command Set
+## Usage Notes
 
-- `quality-check.md`: run `composer lint` and `composer quality`.
-- `docs-verify.md`: verify documentation links and numbered index consistency.
-- `release-readiness.md`: check release workflow preconditions.
+- Keep commands aligned with [AGENTS.md](../../AGENTS.md) and [CLAUDE.md](../../CLAUDE.md).
+- Prefer the repository's existing Composer entry points over ad hoc shell replacements.
+- When docs change, use [docs-verify.md](docs-verify.md) to check relative Markdown links.
 
-## Notes
-
-- Keep commands aligned with `AGENTS.md` and `CLAUDE.md` requirements.
-- Prefer commands that invoke existing composer scripts to avoid drift.

.claude/commands/docs-verify.md

@@ -0,0 +1,39 @@
+# Docs Verify
+
+Validate documentation edits without changing the repository structure.
+
+## Use When
+
+- Any Markdown file under `docs/` changed.
+- The root `README.md`, `CONTRIBUTING.md`, or AI guidance docs changed.
+
+## What To Check
+
+1. Numbered documentation structure still matches `docs/00-architecture` through `docs/04-development`.
+2. Relative Markdown links resolve to existing files.
+3. AI guidance references point to real files instead of placeholders.
+
+## Link Verification Command
+
+Run this from the repository root:
+
+```bash
+rg -n --no-heading --glob '*.md' '\[[^]]+\]\((?!https?://|mailto:|#)([^)#]+)(?:#[^)]+)?\)' README.md CONTRIBUTING.md docs .claude .cursor antigravity jetbrains \
+  | /usr/bin/perl -MFile::Basename=dirname -ne '
+      if (/^([^:]+):\d+:.*\]\(([^)#]+)(?:#[^)]+)?\)/) {
+          my ($file, $target) = ($1, $2);
+          next if $target =~ m{^(https?://|mailto:|#)};
+          my $path = $target =~ m{^/} ? $target : dirname($file) . "/" . $target;
+          if (!-e $path) {
+              print "$file -> $target\n";
+              $bad = 1;
+          }
+      }
+      END { exit($bad // 0); }
+  '
+```
+
+## Expected Outcome
+
+- The command prints nothing and exits successfully.
+- If it reports missing targets, fix the links or the referenced files before completion.

.claude/commands/quality-check.md

@@ -0,0 +1,27 @@
+# Quality Check
+
+Run the repository validation flow before handing off changes.
+
+## Use When
+
+- Source code, tests, or quality configuration changed.
+- You need the minimum final validation expected by [AGENTS.md](../../AGENTS.md) and [CLAUDE.md](../../CLAUDE.md).
+
+## Repository Constraints
+
+- Preserve the public API exposed from `src/`.
+- Keep the package identity intact: layered HTTP client, middleware pipeline, structured logging, and MongoDB logging support.
+- Do not remove runtime assets such as `config/`, `scripts/`, `phpbench.json`, or Docker files.
+
+## Standard Flow
+
+1. Run `composer lint`.
+2. Run `composer quality`.
+3. If documentation changed, run the procedure in [docs-verify.md](docs-verify.md).
+4. If coverage-sensitive files changed, run `composer test:coverage`.
+
+## Expected Outcome
+
+- Linting, static analysis, and the standard test suite pass.
+- Any failures are fixed at the root cause rather than suppressed.
+- The final response calls out anything that could not be validated.

.claude/commands/release-readiness.md

@@ -0,0 +1,26 @@
+# Release Readiness
+
+Review release prerequisites before tagging or merging release-sensitive changes.
+
+## Use When
+
+- Version metadata, changelog, workflows, or publishing configuration changed.
+- A release tag is about to be created.
+
+## Required Checks
+
+1. Run `composer lint`.
+2. Run `composer quality`.
+3. Run [docs-verify.md](docs-verify.md) if release notes or documentation changed.
+
+## Release Preconditions
+
+- `CHANGELOG.md` reflects the intended release.
+- Workflow files under `.github/workflows/` still match the documented release process.
+- Optional publishing secrets are treated as optional and not assumed to exist locally.
+- Any Packagist notification step remains non-destructive when secrets are missing.
+
+## Expected Outcome
+
+- The branch is ready for the release workflow's `validate`, `release`, and optional `publish` stages.
+- Any repo-specific divergence from DTO is documented rather than hidden.

.cursor/rules/README.md

@@ -1,18 +1,14 @@
 # Cursor Rules
 
-Workspace-specific coding rules for Cursor-based workflows.
+Workspace-specific rule files for Cursor-based workflows.
 
-## Current Status
+## Available Rules
 
-No dedicated rule files are committed yet.
-
-## Suggested Rule Topics
-
-- Preserve public API compatibility in `src/`.
-- Keep docs structure aligned with DTO-style numbered indexes.
-- Require running `composer lint` and `composer quality` before completion.
+- `api-stability.mdc`: preserve package API and identity in `src/`.
+- `docs-structure.mdc`: keep docs aligned with the numbered structure and valid local links.
+- `validation-gates.mdc`: require the repo validation contract before completion.
 
 ## Maintenance
 
-- Update this index when new rule files are added.
-- Mirror critical constraints from `AGENTS.md` to avoid conflicting guidance.
+- Mirror critical constraints from [AGENTS.md](../../AGENTS.md) and [CLAUDE.md](../../CLAUDE.md) without introducing conflicting instructions.
+- Update this index whenever a rule file is added, renamed, or removed.

.cursor/rules/api-stability.mdc

@@ -0,0 +1,11 @@
+---
+description: Preserve the public API and package identity for jooservices/client changes under src/
+globs:
+  - src/**/*.php
+alwaysApply: false
+---
+
+- Preserve public API compatibility unless the task explicitly requires a breaking change.
+- Keep the package identity intact: layered HTTP client, middleware pipeline, structured logging, and MongoDB logging support.
+- Prefer minimal diffs that solve the root problem without rewriting unaffected modules.
+- Do not remove runtime assets or contract-level abstractions to satisfy local tests.

.cursor/rules/docs-structure.mdc

@@ -0,0 +1,18 @@
+---
+description: Keep repository documentation aligned with the numbered DTO-style docs structure and valid local links
+globs:
+  - README.md
+  - CONTRIBUTING.md
+  - docs/**/*.md
+  - ai/**/*.md
+  - .claude/**/*.md
+  - .cursor/**/*.md
+  - antigravity/**/*.md
+  - jetbrains/**/*.md
+alwaysApply: false
+---
+
+- Keep documentation organized around the numbered structure under `docs/00-architecture` through `docs/04-development`.
+- Update related AI guidance files when logging behavior, MongoDB logging schema, or live-network diagnostics change.
+- Prefer fixing stale links and references immediately instead of leaving placeholder guidance behind.
+- After doc edits, verify relative Markdown links resolve locally.

.cursor/rules/validation-gates.mdc

@@ -0,0 +1,19 @@
+---
+description: Require the standard validation gates before completing jooservices/client changes
+globs:
+  - composer.json
+  - phpcs.xml
+  - phpmd.xml
+  - phpstan.neon
+  - phpunit.xml
+  - src/**/*.php
+  - tests/**/*.php
+  - docs/**/*.md
+  - .github/workflows/**/*.yml
+alwaysApply: false
+---
+
+- Before finalizing code changes, run `composer lint` and `composer quality`.
+- If documentation changed, also run the docs verification workflow documented in `.claude/commands/docs-verify.md`.
+- If coverage-sensitive behavior changed, run `composer test:coverage` and call out any intentional divergence from DTO.
+- If a required check cannot be run, state that clearly in the final handoff.

.github/labeler.yml

@@ -1,30 +1,33 @@
-documentation:
+'tests':
   - changed-files:
-      - any-glob-to-any-file:
-          - 'docs/**'
-          - '*.md'
+      - any-glob-to-any-file: 'tests/**/*'
 
-ci:
+'documentation':
   - changed-files:
       - any-glob-to-any-file:
-          - '.github/workflows/**'
+          - '**.md'
+          - 'docs/**/*'
 
-quality:
+'dependencies':
   - changed-files:
       - any-glob-to-any-file:
-          - 'phpstan.neon'
-          - 'phpcs.xml'
-          - 'phpmd.xml'
-          - 'pint.json'
-          - '.php-cs-fixer.dist.php'
           - 'composer.json'
+          - 'composer.lock'
 
-source:
+'ci/cd':
   - changed-files:
       - any-glob-to-any-file:
-          - 'src/**'
+          - '.github/**/*'
+          - 'captainhook.json'
 
-tests:
+'configuration':
   - changed-files:
       - any-glob-to-any-file:
-          - 'tests/**'
+          - '**.xml'
+          - '**.neon'
+          - '.php-cs-fixer.dist.php'
+          - '.editorconfig'
+
+'source':
+  - changed-files:
+      - any-glob-to-any-file: 'src/**/*'