Rewrite the contributor guide and tidy the repo docs

.github/pull_request_template.md

@@ -1,15 +1,26 @@
-<!-- 
-Please include a summary of the change and which issue is fixed. Please also include relevant motivation and context. List any dependencies that are required for this change. 
+<!--
+Title: a short descriptive sentence covering the whole change — sentence case, no trailing
+period, no `type(scope):` prefix. "Add an SDL3 backend to imgui-lwjgl3", not
+"feat(lwjgl3): add SDL3 backend". The type is carried by the label.
+See CONTRIBUTING.md → "Pull requests".
 -->
 
+## Summary
+
+<!-- What changes and why. One or two sentences. Required. -->
+
 ## Type of change
 
-<!-- 
-Please check options that are relevant.
--->
+<!-- Please check options that are relevant. -->
 
 - [ ] Minor changes or tweaks (quality of life stuff)
 - [ ] Bug fix (non-breaking change which fixes an issue)
 - [ ] New feature (non-breaking change which adds functionality)
 - [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
 - [ ] This change requires a documentation update
+
+## Notes for reviewer
+
+<!-- Design decisions, deliberate scope boundaries, follow-ups left for later. Omit if none. -->
+
+<!-- Closes #<issue> -->

.gitignore

@@ -16,6 +16,10 @@ logs/
 *.iws
 .idea/
 
+# Eclipse / VS Code Java (Buildship) compile output.
+# Only per-module bin/ — the root bin/ holds tracked native libs.
+/*/bin/
+
 # Package Files #
 *.jar
 *.war

AGENTS.md

@@ -16,9 +16,13 @@ upgrading submodules, and the codegen-internals conventions. The everyday conven
 - **`.claude/docs/patterns.md`** — recurring patterns when adding to the binding (the
   codegen loop, annotated stubs, struct wrappers, out-parameter `Im*` wrappers, module
   boundaries, application lifecycle).
-- **`docs/CONTRIBUTING.md`** — PR/commit workflow. Includes the conventional-commit
-  format and, importantly, the **`Co-authored-by` trailer rule for AI-assisted commits**
-  and the "you are responsible for the change" rule. Read it before opening a PR.
+- **`CONTRIBUTING.md`** — the human-facing contributor guide, and the authority on
+  everything commit- and release-shaped: the conventional-commit types/scopes tables, PR
+  title and body rules (PRs are squash-merged, so the **PR title must be a valid commit
+  header**), label mapping, the versioning scheme (version tracks Dear ImGui, so it can
+  never signal a break), the release procedure, and — importantly — the **`Co-authored-by`
+  trailer rule for AI-assisted commits** plus the "you are responsible for the change"
+  rule. Read it before writing a commit message or opening a PR.
 
 If anything below conflicts with those files, the dedicated file wins — update it
 there, not here.
@@ -196,11 +200,28 @@ Use `providers.exec { ... }` for shell-outs, never `.execute()`. Capture resolve
 
 ## PR workflow
 
-The full commit-message format, the conventional-commit types/scopes, and the
-mandatory `Co-authored-by` trailer for AI-assisted commits are documented in
-`docs/CONTRIBUTING.md` — follow that. The rule that submodule bumps, Gradle/deps
-bumps, and codegen-tooling changes each go in their own PR is in
-`.claude/rules/guardrails.md` ("Don't merge submodule bumps with feature work").
+`CONTRIBUTING.md` is the authority here — follow it, don't paraphrase it:
+
+- **Commit messages** → "Commit message format". Types (`feat|fix|perf|refactor|docs|test|build|chore|revert`)
+  and scopes (`api|native|generator|vendor|lwjgl3|app|example|deps|ci|gradle|readme|agents|contributing`)
+  are fixed tables — pick from them, never invent a scope. `!` in the header requires a
+  `BREAKING CHANGE:` footer.
+- **PR title** → a descriptive prose sentence covering the whole change, sentence case, **no**
+  `type(scope):` prefix — the type is carried by the label, so apply exactly one from the mapping
+  table there (one label per commit type; `build(deps)` takes `deps`), plus `breaking-change` on
+  top whenever the header carries `!`. The conventional header is written into the squash subject
+  at merge time, not the title.
+- **AI-assisted commits** → the `Co-authored-by` trailer is mandatory, family-level model name
+  only. Strip versioned model names, session URLs, and "Generated with …" lines that tooling
+  adds by default, and check the trailer survives the squash.
+- **Releases** → "Releases". Tag-driven (`git describe` is the version of record), version
+  tracks Dear ImGui's `MAJOR.MINOR`, so a breaking change is only ever visible via `!`, the
+  footer, the `breaking-change` label, and the release notes. Never cut a release on stale
+  `bin/` natives.
+
+The rule that submodule bumps, Gradle/deps bumps, and codegen-tooling changes each go in their
+own PR is in `.claude/rules/guardrails.md` ("Don't merge submodule bumps with feature work")
+and restated in `CONTRIBUTING.md` § "Before you start".
 
 Operational guidance on top of those:
 

CLAUDE.md

@@ -2,22 +2,10 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-See [AGENTS.md](AGENTS.md) — it is the canonical guidance for AI agents in this repo and covers everything Claude Code
-needs:
+Read [AGENTS.md](AGENTS.md) — it is the canonical and authoritative guidance for AI agents in this repo, covering
+project layout, build & test commands, the codegen workflow, submodule bumps, gotchas, conventions, and the PR process.
 
-- What the repo is (JNI binding for Dear ImGui + extensions, codegen-driven multi-module Gradle build).
-- Project layout (`imgui-binding/`, `imgui-lwjgl3/`, `imgui-app/`, `buildSrc/`, `include/` submodules, etc.).
-- The **golden rule**: never edit `imgui-binding/src/generated/java/` — it is regenerated from annotated sources in
-  `imgui-binding/src/main/java/`. Workflow: edit source → `./gradlew :imgui-binding:generateApi` → commit both trees
-  together.
-- Build & test commands (`compileJava`, `javadoc`, `generateApi`, `generateAst`, `generateLibs`, `build`) and the visual
-  smoke-test flow for backend/font/example changes.
-- Submodule-bump procedure for Dear ImGui and extensions, including AST regeneration scope rules.
-- Gotchas: doclint-vs-C++ comment patterns, vendor patches, `GenerateLibs.groovy` literal-string rewrites, AST drift,
-  rebase strategy for codegen output, submodule sync after branch switch, `bin/` ownership by CI.
-- Design conventions (dual font loader: stb_truetype + FreeType).
-- Codegen-internals conventions for `buildSrc/` (Spoon generic-type bounds, Gradle 9 configuration cache).
-- PR workflow and merge-ordering guidance.
+The golden rule from there, repeated because it is easy to trip over: **never edit
+`imgui-binding/src/generated/java/`** — it is regenerated from annotated sources in `imgui-binding/src/main/java/`.
 
-Treat `AGENTS.md` as authoritative. If something here ever conflicts with `AGENTS.md`, `AGENTS.md` wins — update it
-there, not here.
+If anything here ever conflicts with `AGENTS.md`, `AGENTS.md` wins — update it there, not here.