Add skills, instruction files, copilot-setup-steps workflow, and .java-version pin

.github/README.md

@@ -0,0 +1,13 @@
+# GitHub Copilot Chat Customization
+
+This directory contains GitHub Copilot customization files for the retrofit-graphql repository.
+
+## Structure
+
+- `instructions/` – Repository-specific context and guidance automatically applied to Copilot sessions.
+- `skills/` – Reusable skill definitions for recurring tasks such as Gradle builds, KDoc, and build dependency management.
+- `workflows/` – GitHub Actions workflows, including `copilot-setup-steps.yml` for pre-warming the Copilot agent environment.
+
+## Usage
+
+Files in `instructions/` are automatically recognized by GitHub Copilot to provide enhanced assistance tailored to the retrofit-graphql library. Skills in `skills/` can be invoked explicitly when working on specific concerns such as low-RAM Gradle builds or KDoc updates.

.github/instructions/build-logic.instructions.md

@@ -0,0 +1,16 @@
+---
+description: Use when editing Gradle files, module dependencies, Dokka configuration, version catalog entries, GitHub workflows, or buildSrc logic in retrofit-graphql.
+applyTo: build.gradle.kts, settings.gradle.kts, gradle/**/*.toml, buildSrc/**/*.kt, */build.gradle.kts, .github/workflows/*.yml
+---
+
+# Build Logic Guidance
+
+- Prefer the shared `co.anitrend.retrofit.graphql` Gradle plugin and `buildSrc` helpers over duplicating Android, Kotlin, Dokka, Spotless, publishing, or test configuration in individual modules.
+- The pinned Java and Kotlin toolchain is 21. Keep new build logic compatible with `.java-version` (`21.0.8`) and the shared Android configuration. The `.java-version` file is read by `jenv` on local developer machines for automatic Java version selection; CI uses `actions/setup-java` instead.
+- Add or update dependency versions in `gradle/libs.versions.toml` first, then reference the alias from modules or build logic.
+- The `:app` module is excluded from the Gradle build when the `CI` environment variable is set (see `settings.gradle.kts`). Only `:library` is built and tested in CI.
+- Shared Android defaults come from `buildSrc`, including `compileSdk = 35`, `minSdk = 23`, `targetSdk = 35`, JUnit Platform, Kotlin toolchain 21, and packaging exclusions.
+- Shared formatting comes from `buildSrc/...AndroidConfiguration.kt` (Spotless configuration) and the license header file under `spotless/copyright.kt`.
+- Shared documentation behavior comes from `buildSrc/...AndroidOptions.kt` (Dokka task configuration) and `.github/workflows/gradle-dokka.yml`.
+- If you need a new convention across modules, prefer adding it once in `buildSrc` instead of repeating it in each `build.gradle.kts`.
+- When validating Gradle changes locally, pair the work with the existing `jenv-gradle-low-ram` skill if JDK alignment or memory pressure becomes a problem.

.github/instructions/context-maintenance.instructions.md

@@ -0,0 +1,17 @@
+---
+description: Use when making architecture changes, module graph changes, public API shifts, build logic updates, documentation workflow changes, or editing repository customizations in retrofit-graphql. Keeps instructions, skills, and consumer-facing context aligned with current repository behavior.
+applyTo: build.gradle.kts, settings.gradle.kts, gradle/**/*.toml, buildSrc/**/*.kt, */build.gradle.kts, library/src/main/**/*.kt, .github/instructions/*.md, .github/skills/**, README.md
+---
+
+# Context Maintenance Guidance
+
+- When a change materially alters repository reality, update the relevant repo guidance in the same patch instead of leaving instructions and skills stale.
+- Treat the following as context-bearing assets that may need maintenance after major changes: `.github/instructions/*.md`, `.github/skills/**`, and `README.md`.
+- Audit repo guidance when you change module boundaries, shared build conventions, Dokka behavior, Retrofit integration patterns, or consumer-facing extension points.
+- Audit KDoc and Dokka guidance when public APIs, annotation semantics, converter behavior, file discovery contracts, logger interfaces, or downstream integration patterns change.
+- Audit the `retrofit-graphql-build-dependencies` and `retrofit-graphql-reference-map` skills when the module list changes, a package gains a new responsibility, or the build and publishing workflow changes.
+- Remove or rewrite contradictory guidance instead of layering new instructions on top of obsolete ones.
+- Prefer updating an existing instruction or skill when the workflow still fits; add a new instruction or skill only when a genuinely new recurring concern appears.
+- Keep changes specific and low-churn: update only the files whose guidance is no longer true.
+- If a change affects how consumers should integrate, configure, or extend the library, update the relevant consumer-facing guidance in the same change.
+- If repository memory is available, record durable repo facts after significant architectural or workflow changes so future tasks start with current context.

.github/instructions/kdoc-dokka.instructions.md

@@ -0,0 +1,20 @@
+---
+description: Use when adding or changing public Kotlin APIs, KDoc, Dokka output, class docs, function docs, annotation docs, or property docs in the retrofit-graphql library module.
+applyTo: library/src/main/**/*.kt
+---
+
+# KDoc And Dokka Guidance
+
+- Treat KDoc as consumer documentation. The generated Dokka site is how downstream apps learn the library surface: `https://anitrend.github.io/retrofit-graphql/`.
+- Document every new or changed public or protected class, interface, object, enum, annotation, function, and property that a consumer may touch.
+- Write documentation for someone outside this repo who does not already know the architecture. Explain what the API is for, when to use it, and which part of the library it belongs to.
+- For annotations such as `@GraphQuery` and `@GraphMutation`, document the expected argument format, the assets folder path convention, and what happens at runtime when the annotation is processed.
+- For converter and factory types, document the Retrofit integration contract: how to register the converter, which request types it handles, and any ordering requirements relative to other converters.
+- For discovery and plugin types, document the extension contract: what implementations must return, which lifecycle events trigger discovery, and any threading or nullability assumptions.
+- For logger types, document the levels, filtering behavior, and how to register a custom logger with the converter factory.
+- For classes with important collaborators, link to nearby types with KDoc references instead of forcing consumers to search the repo manually.
+- Preserve the existing house style: a short summary first, then focused detail, with `@param`, `@property`, `@return`, `@throws`, `@see`, and `@since` where they add value.
+- Do not invent version history. Only add `@since` when the version is already known or established in adjacent code.
+- Avoid placeholder KDoc that only restates the type name. Explain behavior, expectations, and integration points.
+- If behavior changes, update the docs in the same patch so the published site stays trustworthy.
+- Packages under `.internal` are suppressed from Dokka. If an API is meant for library consumers, keep it in a documented public package.

.github/skills/jenv-gradle-low-ram/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: jenv-gradle-low-ram
+description: 'Align jenv with .java-version and run Gradle reliably on low-RAM machines. Use for Java mismatch errors, Gradle OOMs, daemon memory pressure, and selecting safe build flags.'
+argument-hint: 'Describe your target task and available RAM, for example: assembleDebug on 8GB RAM'
+---
+# Jenv + Gradle Low-RAM Workflow
+
+## What This Skill Produces
+
+- A shell where `java` and Gradle use the Java version pinned by `.java-version`.
+- A repeatable Gradle command profile tuned for constrained memory.
+- Verification checks to confirm version alignment and build stability.
+
+## When To Use
+
+- Any time `./gradlew` is about to be invoked in this repository.
+- Especially important for low-RAM machines where daemon/worker pressure can destabilize builds.
+- Required when verifying that Java from `.java-version` is the active runtime for Gradle.
+
+## Context
+
+This repository pins Java `21.0.8` in `.java-version`. On developer machines with `jenv` installed, navigating to the project root automatically selects that JDK. In CI, `actions/setup-java` with `java-version: 21` handles selection instead. The `copilot-setup-steps.yml` workflow mirrors the CI approach.
+
+## Procedure
+
+1. Detect the required Java version.
+
+```bash
+cat .java-version
+```
+
+2. Verify `jenv` is installed and initialized.
+
+```bash
+command -v jenv
+jenv versions
+jenv version
+```
+
+Decision point:
+
+- If `jenv` is not found, install and initialize it in your shell startup.
+- If `jenv` is found but `jenv version` does not match `.java-version`, continue to step 3.
+
+3. Align local Java to the repository pin.
+
+```bash
+required_java="$(cat .java-version)"
+jenv local "$required_java"
+```
+
+Decision point:
+
+- If `jenv local` fails because the version is missing, install that JDK and run `jenv add <jdk-path>`, then retry.
+
+4. Confirm runtime alignment before any Gradle task.
+
+```bash
+java -version
+./gradlew -version
+```
+
+Quality check:
+
+- Gradle JVM version in `./gradlew -version` must match the `.java-version` major version (21).
+
+5. Run Gradle with low-memory-safe defaults.
+
+Preferred one-off profile for a debug build (`:app` module; not available in CI):
+
+```bash
+./gradlew --no-daemon --max-workers=2 \
+  -Dorg.gradle.jvmargs="-Xmx1536m -XX:MaxMetaspaceSize=512m -Dfile.encoding=UTF-8" \
+  :app:assembleDebug
+```
+
+For library unit tests:
+
+```bash
+./gradlew --no-daemon --max-workers=2 \
+  -Dorg.gradle.jvmargs="-Xmx1792m -XX:MaxMetaspaceSize=512m -Dfile.encoding=UTF-8" \
+  :library:test
+```
+
+For Spotless formatting check:
+
+```bash
+./gradlew --no-daemon --max-workers=2 \
+  -Dorg.gradle.jvmargs="-Xmx1536m -XX:MaxMetaspaceSize=512m -Dfile.encoding=UTF-8" \
+  spotlessCheck
+```
+
+6. If memory pressure continues, downgrade concurrency.
+
+```bash
+./gradlew --no-daemon --max-workers=1 -Dorg.gradle.parallel=false :library:test
+```
+
+7. If builds are stable and you want persistence, prefer user-local Gradle overrides (avoid committing repo-wide memory changes).
+
+Suggested entries for `~/.gradle/gradle.properties`:
+
+```properties
+org.gradle.daemon=false
+org.gradle.parallel=false
+org.gradle.workers.max=2
+org.gradle.jvmargs=-Xmx1536m -XX:MaxMetaspaceSize=512m -Dfile.encoding=UTF-8
+```
+
+## Troubleshooting Branches
+
+- `jenv version` correct but `java -version` wrong:
+  Ensure shell init runs `eval "$(jenv init -)"` and enable export plugin with `jenv enable-plugin export`.
+- `Gradle daemon disappeared unexpectedly`:
+  Retry with `--no-daemon --max-workers=1` and lower `-Xmx` if the OS is reclaiming memory aggressively.
+- Kotlin compile OOM:
+  Keep workers low, disable parallel, and run module-targeted tasks (`:library:test` or `:app:assembleDebug`) instead of full-project builds.
+- `:app` not found:
+  The app module is excluded when the `CI` environment variable is set. Run debug builds locally without `CI` set, or unset it temporarily.
+
+## Completion Checks
+
+- `.java-version` and `jenv version` resolve to the same Java release.
+- `./gradlew -version` reports the expected JVM.
+- Target Gradle task completes without OOM or daemon crash.
+- Machine remains responsive during build (no prolonged swap thrash).
+
+## Fast Invocation Examples
+
+- "Align my shell to `.java-version` and run debug build with 8GB RAM settings"
+- "I get class file major version errors; fix jenv and verify Gradle JVM"
+- "Run library unit tests with a low-memory Gradle profile and fallback if OOM occurs"

.github/skills/retrofit-graphql-build-dependencies/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: retrofit-graphql-build-dependencies
+description: 'Understand and change retrofit-graphql build logic, module dependencies, version catalog entries, Dokka setup, and shared Gradle conventions. Use for buildSrc edits, new dependencies, or documentation pipeline work.'
+argument-hint: 'Describe the dependency, Gradle change, or build pipeline task you need to make'
+---
+
+# Retrofit GraphQL Build And Dependencies
+
+## What This Skill Produces
+
+- A safe path for changing module dependencies or shared build logic.
+- A map of where versions, plugins, Dokka, Spotless, and Android defaults are defined.
+- Clear guidance on whether a change belongs in a module build file, the version catalog, or `buildSrc`.
+
+## When To Use
+
+- Adding or upgrading dependencies.
+- Changing module relationships.
+- Editing Dokka, Spotless, JDK, Android, publishing, or test conventions.
+- Understanding how the converter, annotation, discovery, and model packages are wired.
+
+## Procedure
+
+1. Read the [build map](./references/build-map.md) to find the owning file for the convention you want to change.
+2. If the change introduces or upgrades a dependency, add the version and alias in `gradle/libs.versions.toml` first.
+3. If the behavior should apply to both modules, implement it in `buildSrc` instead of duplicating it in both `build.gradle.kts` files.
+4. Remember that `:app` is excluded from the Gradle build when the `CI` environment variable is set; only `:library` is built and tested in CI.
+5. Keep Dokka, Spotless, and test behavior aligned with the shared configuration in `buildSrc`.
+6. When running Gradle locally, use the existing `jenv-gradle-low-ram` skill if Java selection or memory pressure becomes an issue.
+
+## References
+
+- [build map](./references/build-map.md)

.github/skills/retrofit-graphql-build-dependencies/references/build-map.md

@@ -0,0 +1,31 @@
+# Build Map
+
+Use this map to choose the right build file before editing.
+
+| Concern | Primary files | Notes |
+| --- | --- | --- |
+| Module includes | `settings.gradle.kts` | Includes `:library` always; includes `:app` only when `CI` env var is not set |
+| Root build configuration | `build.gradle.kts` | Top-level plugin declarations and repository configuration |
+| Shared plugin entry point | `buildSrc/.../plugin/CorePlugin.kt` | Applies Android plugin, Dokka, Spotless, publishing, sources, and dependencies based on module type |
+| Shared Android defaults | `buildSrc/.../components/AndroidConfiguration.kt` | SDK levels (`compileSdk=35`, `minSdk=23`, `targetSdk=35`), JUnit Platform, Kotlin toolchain 21, packaging exclusions, Spotless |
+| Shared dependency strategy | `buildSrc/.../strategy/DependencyStrategy.kt` | Default Kotlin, Retrofit, OkHttp, coroutines, and test libraries per module type |
+| Shared Dokka behavior | `buildSrc/.../components/AndroidOptions.kt` | `dokkaHtml` task, `reportUndocumented = true`, internal packages suppressed, Android docs linked |
+| Shared formatting | `buildSrc/.../components/AndroidConfiguration.kt` (Spotless config), `spotless/copyright.kt` | Ktlint and license header configuration |
+| Publishing options | `buildSrc/.../components/AndroidOptions.kt` | Sources jar, classes jar, Maven publication for JitPack |
+| Dependency versions and aliases | `gradle/libs.versions.toml` | Add or update aliases here first |
+| Library build | `library/build.gradle.kts` | Applies the shared plugin; no module-specific overrides needed for standard changes |
+| Sample app build | `app/build.gradle.kts` | Applies the shared plugin; Room compiler options, build config fields from `.config/` |
+| Dokka publication | `.github/workflows/gradle-dokka.yml` | Runs on `develop`, generates `library/build/docs/dokka`, deploys to `docs` branch |
+
+## Module Dependency Snapshot
+
+- `library`: standalone Android library module with no project-level dependencies.
+- `app`: sample application that depends on `:library` for integration demonstration.
+
+## Edit Strategy
+
+- New library version or alias: `libs.versions.toml`.
+- Cross-module convention: `buildSrc`.
+- One module only: that module's `build.gradle.kts`.
+- Documentation generation or publish behavior: Dokka config in `buildSrc/...AndroidOptions.kt` plus the workflow file.
+- Memory or JVM tuning: `gradle.properties` (repo-wide) or `~/.gradle/gradle.properties` (user-local, preferred for personal overrides).

.github/skills/retrofit-graphql-kdoc-dokka/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: retrofit-graphql-kdoc-dokka
+description: 'Write or improve KDoc for public APIs in retrofit-graphql. Use for Dokka updates, annotation docs, converter docs, discovery plugin docs, logger docs, and explaining how consumers should integrate or extend the library.'
+argument-hint: 'Describe the public API, package, or documentation gap you need to cover'
+---
+
+# Retrofit GraphQL KDoc And Dokka
+
+## What This Skill Produces
+
+- Consumer-facing KDoc that reads well on the published Dokka site: `https://anitrend.github.io/retrofit-graphql/`.
+- Documentation that explains annotation contracts, converter behavior, discovery extension points, and logger integration.
+- A repeatable checklist for updating docs whenever public behavior changes.
+
+## When To Use
+
+- Adding or changing a public class, interface, annotation, function, property, or enum.
+- Explaining how a downstream app should register, configure, or extend the converter or its plugins.
+- Tightening documentation before a release or after a behavior change.
+
+## Procedure
+
+1. Identify the public or protected surface that changed.
+2. Read the [KDoc checklist](./references/kdoc-checklist.md) and match the API shape to the closest template.
+3. Document what the API does, when to use it, and what a consumer is expected to provide or observe.
+4. For annotations, explain the expected value format, the asset path convention, and what the converter does with the annotation at runtime.
+5. For converter and factory types, document the Retrofit registration contract, supported request types, and any ordering requirements.
+6. For discovery and plugin interfaces, document the extension contract: what the implementation must return and when it is called.
+7. Link adjacent types with KDoc references so Dokka helps consumers navigate the API surface.
+8. If the type belongs to a new package, consider whether nearby package or module docs also need an update.
+
+## Quality Bar
+
+- Summary first, details second.
+- Avoid tautologies such as repeating the type name without explaining behavior.
+- Keep docs aligned with real behavior in the code, not the intended behavior from an older implementation.
+
+## References
+
+- [KDoc checklist](./references/kdoc-checklist.md)