feat: upgrade and create agents.md

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

@@ -0,0 +1,186 @@
+---
+name: update-sdk
+description: Regenerate relewise-sdk-java from the Generator project with a strict git and PR flow. Use when asked to update generated Java 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 (Java)
+
+## Goal
+Regenerate SDK code in `src/src/main/java/com/relewise/client` 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
+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/src/main/java/com/relewise/client/model/*` generated model files
+- generated client surfaces in `src/src/main/java/com/relewise/client/*`
+- generator changes only when intentionally included
+
+If unrelated files changed unexpectedly, stop and investigate.
+
+## Validation (Required)
+Run from repository root:
+
+1. Package:
+```powershell
+mvn --batch-mode -DskipTests package --file src/pom.xml
+```
+
+2. Resource/version metadata:
+```powershell
+mvn resources:resources --file src/pom.xml
+```
+
+3. Tests:
+```powershell
+mvn --batch-mode test --file src/pom.xml
+```
+
+Integration-heavy tests depend on `DATASET_ID` and `API_KEY`.
+
+When credentials are unavailable, run a credential-independent subset and report integration-heavy coverage as not run:
+
+```powershell
+mvn --batch-mode -Dtest=ClientConstructionTest,DateTimeSerializationTest test --file src/pom.xml
+```
+
+## Acceptance Criteria
+Treat update as successful only when:
+- generation succeeds (`generate.ps1` or `generate.sh`)
+- package/resources commands succeed
+- test 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(java): 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 Java SDK code via Generator
+- Updated generated models/client surfaces
+
+## Validation
+- `./generate.ps1`: <result>
+- `mvn --batch-mode -DskipTests package --file src/pom.xml`: <result>
+- `mvn resources:resources --file src/pom.xml`: <result>
+- `mvn --batch-mode test --file src/pom.xml`: <result or not run>
+- `mvn --batch-mode -Dtest=ClientConstructionTest,DateTimeSerializationTest test --file src/pom.xml`: <result or not run>
+
+## Notes
+- <known issues or limitations>
+"@ | Set-Content $prBodyPath
+
+$prUrl = gh pr create --base main --head $branchName --title "chore(java): 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-java/compare/main...$branchName?expand=1"
+Write-Host "PR title: chore(java): 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-java code and open Trello-linked PR"
+  default_prompt: "Use $update-sdk to regenerate relewise-sdk-java, validate build and tests, and create a branch and PR with the Trello URL as the first line."

.github/workflows/CI.yml

@@ -9,18 +9,18 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v1
+        uses: actions/checkout@v6
 
-      - name: Setup .NET 7
-        uses: actions/setup-dotnet@v1
+      - name: Setup .NET 10
+        uses: actions/setup-dotnet@v5
         with:
-          dotnet-version: '9.0.x'
+          dotnet-version: '10.0.x'
 
       - name: Generate Java classes
         run: ./generate.sh
 
       - name: Set up JDK 17
-        uses: actions/setup-java@v3
+        uses: actions/setup-java@v4
         with:
           java-version: '17'
           distribution: 'temurin'

.github/workflows/publish.yml

@@ -17,12 +17,12 @@ jobs:
 
     steps:
       - name: Checkout source code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
-      - name: Setup .NET 7
-        uses: actions/setup-dotnet@v3
+      - name: Setup .NET 10
+        uses: actions/setup-dotnet@v5
         with:
-          dotnet-version: '9.0.x'
+          dotnet-version: '10.0.x'
 
       - name: Generate Java classes
         run: ./generate.sh

AGENTS.md

@@ -0,0 +1,113 @@
+# AGENTS.md
+
+## Purpose
+This file is the operating guide for contributors and coding agents working in `relewise-sdk-java`.
+
+The repository is a Java SDK with generated client/models and Maven-based build/release workflows. Follow this guide to keep changes scoped, verifiable, and CI-aligned.
+
+## Repository Map
+- `src/pom.xml`: Maven project manifest (packaging, test, release profile).
+- `src/src/main/java/com/relewise/client`: Java SDK source.
+- `src/src/test/java/com/relewise/client`: JUnit tests.
+- `Generator`: .NET generator project for Java SDK code.
+- `.github/workflows`: CI, publish, and Trello workflows.
+- `generate.ps1` / `generate.sh`: generation entry points.
+- `DEVELOPMENT.md`: local development notes.
+- `PUBLISH.md`: release workflow and troubleshooting notes.
+- `openapitools.json`, `swagger.json`: generation/reference assets.
+
+## 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 generation scripts from repository root.
+- Run Maven commands against `src/pom.xml`.
+- Keep changes minimal and related to the task.
+- Do not commit secrets (`DATASET_ID`, `API_KEY`, Sonatype/GPG credentials).
+- Treat generator output as generated code:
+  - `src/src/main/java/com/relewise/client/model` is generator-owned.
+  - Client layers in `src/src/main/java/com/relewise/client` are also generated by current pipeline.
+- Prefer generator changes + regeneration over manual edits in generated files.
+
+## Generation Workflow
+Prerequisite: .NET 10 SDK or newer.
+
+Use one of:
+
+```powershell
+./generate.ps1
+```
+
+```bash
+./generate.sh
+```
+
+The generator writes SDK code into `src/src/main/java/com/relewise/client`.
+
+## Runbook
+Generate SDK code:
+
+```powershell
+./generate.ps1
+```
+
+```bash
+./generate.sh
+```
+
+Build package:
+
+```powershell
+mvn --batch-mode -DskipTests package --file src/pom.xml
+```
+
+Generate `project.properties` for runtime version metadata:
+
+```powershell
+mvn resources:resources --file src/pom.xml
+```
+
+Run tests:
+
+```powershell
+mvn --batch-mode test --file src/pom.xml
+```
+
+## Testing and Credentials
+- Tests use `DATASET_ID` and `API_KEY` from environment (`TestBase`).
+- CI injects credentials from secrets.
+- If credentials are unavailable locally, explicitly report integration-style test coverage as not run.
+
+## Validation Policy (CI-Aligned, Pragmatic)
+- Required for normal changes:
+  - Regenerate when touching generator-owned surfaces.
+  - Run package + test commands against `src/pom.xml`.
+- Required for behavior/API changes:
+  - Run tests covering affected request/response flows.
+- Required for release/publish changes:
+  - Validate relevant release-profile commands as appropriate.
+  - Follow `PUBLISH.md` as source of truth for release operations.
+
+## 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 Java 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: behavior or release surface impacted.
+- Validation: exact commands run and results.
+- Generation note: whether generation scripts were run.
+
+## Known Pitfalls
+- Maven project lives under `src`; root-level `mvn` without `--file src/pom.xml` is wrong.
+- Skipping `mvn resources:resources --file src/pom.xml` can leave client version metadata stale.
+- Manual edits to generated files create drift on next generation run.

DEVELOPMENT.md

@@ -6,8 +6,8 @@ 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 Java 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`.
 ## Development experience
-For the best experience with developing on the SDK we recommend to use a dedicated Java IDE.
+For the best experience with developing on the SDK we recommend to use a dedicated Java IDE.

Generator/Generator.csproj

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