feat: upgrade and create agents.md

.agents/skills/update-sdk/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: update-sdk
+description: Regenerate relewise-sdk-php from the Generator project with a strict git and PR flow. Use when asked to update generated PHP SDK code. Require a Trello card URL, run clean-main preflight checks, create a timestamped chore branch, run generation and validation, then push and open a PR with the Trello URL as the first line.
+---
+
+# Update SDK (PHP)
+
+## Goal
+Regenerate SDK code in `src` from `Generator`, validate the result, and deliver a reviewed PR to `main`.
+
+## Required Input
+Require a Trello card URL before running SDK update work.
+
+If the request does not include a Trello URL:
+- Ask for it.
+- Do not continue until it is provided.
+
+## Preflight Git Safety
+Run from repository root.
+
+1. Require a clean worktree:
+```powershell
+git status --porcelain
+```
+Abort when any output exists.
+
+2. Ensure `origin` exists:
+```powershell
+git remote get-url origin
+```
+Abort on failure.
+
+3. Fetch refs:
+```powershell
+git fetch origin --prune
+```
+Abort on failure.
+
+4. Switch to `main`:
+```powershell
+git switch main
+```
+Abort if switch is not safe.
+
+5. Fast-forward `main`:
+```powershell
+git pull --ff-only origin main
+```
+Abort if not fast-forward.
+
+Do not continue when any preflight step fails.
+
+## Branch Creation
+Use a timestamped branch:
+
+```powershell
+$stamp = Get-Date -Format 'yyyyMMdd-HHmm'
+$branchName = "chore/update-sdk-$stamp"
+```
+
+Abort if branch exists:
+
+```powershell
+git show-ref --verify --quiet "refs/heads/$branchName"
+git ls-remote --exit-code --heads origin $branchName
+```
+
+Create and switch:
+
+```powershell
+git switch -c $branchName
+```
+
+## SDK Regeneration
+1. Install dependencies:
+```powershell
+composer install --no-interaction --no-progress
+```
+
+2. Regenerate SDK code:
+```powershell
+./generate.ps1
+```
+
+Alternative on non-Windows:
+```bash
+./generate.sh
+```
+
+## Expected Changes Check
+Inspect changed files and ensure the update is coherent.
+
+Expected change locations:
+- `src/Models/*` generated model files
+- generated client surfaces in `src/*.php`
+- generator changes only when intentionally included
+
+If unrelated files changed unexpectedly, stop and investigate.
+
+## Validation (Required)
+Run this command:
+
+```powershell
+vendor/bin/phpunit --configuration tests/phpunit.xml --testsuite Unit
+```
+
+Integration-heavy tests depend on `DATASET_ID` and `API_KEY`.
+
+When credentials are unavailable, run the unit subset and report integration-heavy coverage as not run:
+
+```powershell
+vendor/bin/phpunit tests/php/unit --configuration tests/phpunit.xml
+```
+
+## Acceptance Criteria
+Treat update as successful only when:
+- generation succeeds (`generate.ps1` or `generate.sh`)
+- validation command(s) pass for available credentials
+- changed files are expected and reviewable
+
+## Commit, Push, and Pull Request
+1. Commit SDK update changes:
+```powershell
+git add .
+git commit -m "chore(php): update sdk generation ($stamp)"
+```
+
+2. Push branch:
+```powershell
+git push -u origin $branchName
+```
+
+3. Create PR to `main`.
+
+Preferred flow with GitHub CLI:
+```powershell
+$prBodyPath = ".\\update-sdk-pr-body.md"
+@"
+$TrelloCardUrl
+
+## Summary
+- Regenerated PHP SDK code via Generator
+- Updated generated models/client surfaces
+
+## Validation
+- `composer install --no-interaction --no-progress`: <result>
+- `./generate.ps1`: <result>
+- `vendor/bin/phpunit --configuration tests/phpunit.xml --testsuite Unit`: <result>
+- `vendor/bin/phpunit tests/php/unit --configuration tests/phpunit.xml`: <result or not run>
+
+## Notes
+- <known issues or limitations>
+"@ | Set-Content $prBodyPath
+
+$prUrl = gh pr create --base main --head $branchName --title "chore(php): update sdk generation ($stamp)" --body-file $prBodyPath
+if ($LASTEXITCODE -ne 0) { throw 'gh pr create failed.' }
+Write-Host "PR URL: $prUrl"
+```
+
+Manual fallback:
+```powershell
+git push -u origin $branchName
+Write-Host "Create PR: https://github.com/Relewise/relewise-sdk-php/compare/main...$branchName?expand=1"
+Write-Host "PR title: chore(php): update sdk generation ($stamp)"
+Write-Host "PR body file: $prBodyPath"
+```
+
+Keep the Trello URL as the first line of the PR description.
+
+## Output Expectations
+Provide a final summary with:
+- Trello URL used
+- branch name
+- changed file groups
+- validation command results
+- pushed branch URL
+- PR URL, or exact manual fallback instructions

.agents/skills/update-sdk/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Update SDK"
+  short_description: "Regenerate relewise-sdk-php code and open Trello-linked PR"
+  default_prompt: "Use $update-sdk to regenerate relewise-sdk-php, validate tests, and create a branch and PR with the Trello URL as the first line."

.github/workflows/ci.yml

@@ -8,14 +8,14 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v6
 
       - uses: php-actions/composer@v6
 
-      - name: Setup .NET 8 preview
-        uses: actions/setup-dotnet@v1
+      - name: Setup .NET 10
+        uses: actions/setup-dotnet@v5
         with:
-          dotnet-version: '8.0.x'
+          dotnet-version: '10.0.x'
 
       - name: Generate PHP classes
         run: ./generate.sh

.github/workflows/publish.yml

@@ -9,20 +9,20 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v6
 
-      - uses: php-actions/composer@v5
+      - uses: php-actions/composer@v6
 
-      - name: Setup .NET 8 preview
-        uses: actions/setup-dotnet@v1
+      - name: Setup .NET 10
+        uses: actions/setup-dotnet@v5
         with:
-          dotnet-version: '8.0.x'
+          dotnet-version: '10.0.x'
 
       - name: Generate PHP classes
         run: ./generate.sh
 
       - name: PHPUnit Tests
-        uses: php-actions/phpunit@v2
+        uses: php-actions/phpunit@v3
         with:
           bootstrap: vendor/autoload.php
           configuration: tests/phpunit.xml

AGENTS.md

@@ -0,0 +1,112 @@
+# AGENTS.md
+
+## Purpose
+This file is the operating guide for contributors and coding agents working in `relewise-sdk-php`.
+
+The repository is a PHP SDK with generated client/models and integration-heavy tests. Follow this guide to keep changes scoped, reproducible, and aligned with CI.
+
+## Repository Map
+- `src`: PHP SDK source (clients, infrastructure, models, factories).
+- `tests`: PHPUnit bootstrap, env loader, and test suites (`php/integration`, `php/unit`).
+- `Generator`: .NET generator project that writes SDK code into `src`.
+- `.github/workflows`: CI, publish, and Trello automation workflows.
+- `generate.ps1` / `generate.sh`: entry points for code generation.
+- `composer.json`: package metadata and PHP/test dependencies.
+- `DEVELOPMENT.md`: local development notes.
+
+## Repository Skills
+- `update-sdk`:
+  - Location: `.agents/skills/update-sdk/SKILL.md`
+  - Use when asked to regenerate generated SDK code from `Generator`.
+  - This skill enforces Trello URL pre-requisite, clean-main preflight checks, timestamped chore branch creation, validation commands, and Trello-first PR descriptions.
+
+## Core Working Conventions
+- Run commands from repository root unless explicitly noted.
+- Keep changes minimal and directly related to the task.
+- Do not commit secrets (`DATASET_ID`, `API_KEY`, tokens).
+- Treat generator output as generated code:
+  - `src/Models` is generator-owned.
+  - Client surfaces in `src` are also produced by generator workflows.
+- Prefer updating `Generator` + running generation scripts over manual edits in generated files.
+
+## Generation Workflow
+Prerequisite: .NET 10 SDK or newer.
+
+Use one of:
+
+```powershell
+./generate.ps1
+```
+
+```bash
+./generate.sh
+```
+
+Both scripts run the .NET generator and write output to `src`.
+
+## Runbook
+Install dependencies:
+
+```powershell
+composer install
+```
+
+Generate SDK code:
+
+```powershell
+./generate.ps1
+```
+
+```bash
+./generate.sh
+```
+
+Run all tests configured by CI:
+
+```powershell
+vendor/bin/phpunit --configuration tests/phpunit.xml --testsuite Unit
+```
+
+Run unit-only folder (optional fast loop):
+
+```powershell
+vendor/bin/phpunit tests/php/unit --configuration tests/phpunit.xml
+```
+
+## Testing and Credentials
+- Many tests require `DATASET_ID` and `API_KEY`.
+- CI injects those from secrets.
+- Local runs can load them from `tests/.env` via `tests/Bootstrap_phpunit.php` and `tests/DotEnv.php`.
+- If credentials are unavailable, report integration coverage as not run.
+
+## Validation Policy (CI-Aligned, Pragmatic)
+- Required for normal changes:
+  - Run generation if change touches generator-owned code paths.
+  - Run PHPUnit with `tests/phpunit.xml`.
+- Required for behavior/API changes:
+  - Run tests that exercise affected flows.
+  - Include integration-oriented coverage when credentials are available.
+- For workflow/tooling changes:
+  - Validate relevant command paths still run locally.
+
+## SDK Update Guidance
+For generation-driven SDK refresh tasks, prefer using the `update-sdk` skill:
+
+```text
+$update-sdk
+```
+
+Use `update-sdk` when the goal is regenerating PHP SDK code and opening a branch/PR flow tied to a Trello card.
+
+## PR Expectations
+Each PR should include:
+- Scope: what changed and why.
+- Risk notes: behavioral areas potentially impacted.
+- Validation: commands run and outcomes.
+- Generation note: whether `generate.ps1` / `generate.sh` was run.
+
+## Known Pitfalls
+- Manual edits to generated code will drift from generator output.
+- `tests/phpunit.xml` points at `tests/php`, so default suite includes both unit and integration folders.
+- Tests depending on `DATASET_ID`/`API_KEY` fail fast when env is missing.
+- Keep runtime assumptions aligned with `composer.json` (`php: ^8.1`).

DEVELOPMENT.md

@@ -6,7 +6,7 @@ This document describes the process for running this application on your local c
 
 This project uses .NET to automatically generate the models used in the PHP client.
 
-To run the generator you need to have .NET 7 or newer installed on your machine. [Download .NET 7](https://dotnet.microsoft.com/en-us/download/dotnet/7.0)
+To run the generator you need to have .NET 10 or newer installed on your machine. [Download .NET 10](https://dotnet.microsoft.com/en-us/download/dotnet/10.0)
 
 Then to generate the models and clients of the SDK run `generate.ps1` if you're on Windows, else run `generate.sh`.
 

Generator/Generator.csproj

@@ -2,7 +2,7 @@
 
 	<PropertyGroup>
 		<OutputType>Exe</OutputType>
-		<TargetFramework>net8.0</TargetFramework>
+		<TargetFramework>net10.0</TargetFramework>
 		<ImplicitUsings>enable</ImplicitUsings>
 		<Nullable>enable</Nullable>
 	</PropertyGroup>