docs: restructure documentation and optimize README

.copilotignore

@@ -0,0 +1,23 @@
+# Build outputs
+build/
+.gradle/
+.cxx/
+*.apk
+*.aab
+
+# Prebuilt native libraries (large binaries)
+library/src/main/libs/
+library/src/main/jni/ffmpeg/
+library/src/main/jni/ffmpeg-16kb/
+
+# IDE configuration
+.idea/
+*.iml
+local.properties
+
+# OS artifacts
+.DS_Store
+Thumbs.db
+
+# Release artifacts
+demoRelease/

.github/CONTRIBUTING.md

@@ -0,0 +1,64 @@
+# Contributing Guide
+
+## Getting Started
+
+1. Fork the repository
+2. Create a feature branch from `master` (`feat/xxx`, `fix/xxx`, `refactor/xxx`)
+3. Make your changes
+4. Verify the build: `bash tasks.sh --enable-cmake --build`
+5. Submit a pull request to `master`
+
+## Code Standards
+
+- Use **English** for all code comments, commit messages, and PR descriptions
+- Follow conventional-commit format for commits: `feat:`, `fix:`, `refactor:`, `chore:`
+- One logical change per commit
+
+### C++ (Native)
+
+- Follow `.clang-format` (Allman braces, 4-space indent)
+- All code in `namespace CGE {}`
+- No C++ exceptions (compiled with `-fno-exceptions`)
+- Use logging macros: `CGE_LOG_INFO`, `CGE_LOG_ERROR`, `CGE_LOG_KEEP`
+- Inline GLSL via `CGE_SHADER_STRING_PRECISION_H()` / `CGE_SHADER_STRING_PRECISION_M()`
+- Release GL resources (programs, textures, FBOs) along the handler lifecycle
+
+### Java (Android)
+
+- GL operations in `GLSurfaceView` subclasses must use `queueEvent(...)`
+- Load native libraries through `NativeLibraryLoader` only
+- Check `BuildConfig.CGE_USE_VIDEO_MODULE` before referencing FFmpeg classes
+
+### JNI Bridge
+
+- JNI function names: `Java_org_wysaid_nativePort_<Class>_<method>`
+- Always validate JNI parameters (null checks) before dereferencing
+- Never store JNI local references across calls
+
+## Compatibility Rules
+
+- **Do not change** method signatures in `org.wysaid.nativePort.*`
+- **Do not change** existing JNI function names
+- **Do not change** existing filter rule string syntax
+- New methods, filters, and syntax additions are welcome
+
+## FFmpeg / Video Module
+
+All FFmpeg-dependent code must be optional:
+
+- C++: guard with `#ifdef CGE_USE_VIDEO_MODULE`
+- Java: check `BuildConfig.CGE_USE_VIDEO_MODULE`
+- Verify the project compiles with `--disable-video-module`
+
+## Dual Build System
+
+When adding new native source files under `library/src/main/jni/`:
+
+- **CMake**: auto-discovered via `GLOB_RECURSE` — usually no action needed
+- **ndk-build**: update `Android.mk` to explicitly list the new files
+
+## CI
+
+Pull requests trigger CI on three platforms (macOS, Ubuntu, Windows). PRs run a reduced matrix (1 combination per platform); merges to `master` run the full 16-combination matrix.
+
+Ensure all CI checks pass before requesting review.

.github/RELEASE.md

@@ -0,0 +1,56 @@
+# Release Process
+
+This project uses an automated release workflow triggered by version tags.
+
+## Creating a Release
+
+### 1. Update the Version
+
+Edit `versionName` in `build.gradle`:
+
+```gradle
+ext {
+    android = [
+        ...
+        versionName: "3.1.1",
+        ...
+    ]
+}
+```
+
+### 2. Commit and Push
+
+```bash
+git add build.gradle
+git commit -m "chore: bump version to 3.1.1"
+git push
+```
+
+### 3. Tag and Push
+
+```bash
+git tag v3.1.1
+git push origin v3.1.1
+```
+
+## Automated Workflow
+
+When a tag matching `v*.*.*` is pushed, the [release workflow](../.github/workflows/release.yml) will:
+
+1. **Validate** that the tag version matches `versionName` in `build.gradle`
+2. **Build** four AAR variants:
+   - `gpuimage-plus-{version}.aar` — Full with FFmpeg, 4KB page size
+   - `gpuimage-plus-{version}-16k.aar` — Full with FFmpeg, 16KB page size
+   - `gpuimage-plus-{version}-min.aar` — Image-only, 4KB page size
+   - `gpuimage-plus-{version}-16k-min.aar` — Image-only, 16KB page size
+3. **Build** the demo APK (with video module)
+4. **Create** a GitHub release with all artifacts and release notes
+
+## Tag Format
+
+- Official: `v3.1.1`
+- Beta: `v3.1.1-beta1`
+- Alpha: `v3.1.1-alpha1`
+- Release candidate: `v3.1.1-rc1`
+
+The core `X.Y.Z` segments must be numeric. Prerelease suffixes (for example `-beta1`, `-alpha1`, `-rc1`) are allowed, and the full tag version (including any suffix) must exactly match `versionName` in `build.gradle`.

.github/copilot-instructions.md

@@ -1,57 +1,52 @@
 # GitHub Copilot Instructions — android-gpuimage-plus
 
-This repo is a widely-used Android GPU filter library. Prefer **small, safe, backward-compatible** changes.
+Android GPU filter library (C++ & Java). Prefer **small, safe, backward-compatible** changes.
 
-## Non‑negotiables (stability first)
+## Stability Rules
 
-- **Do not break compatibility**: avoid changing public Java APIs, JNI method signatures, or filter rule string syntax.
-- Prefer **additive** changes (new classes/methods/filters) over refactors.
-- Keep FFmpeg/video code **fully optional** (both Java and native side guards).
+- **Never break public API**: `org.wysaid.nativePort.*` Java signatures, JNI method names, and filter rule string syntax are stable contracts.
+- Prefer **additive** changes over refactoring existing code.
+- FFmpeg/video code must remain **fully optional** — guard with `disableVideoModule` (Java/Gradle) / `CGE_USE_VIDEO_MODULE` (C++).
 
-## Where things live (only what’s non-obvious)
+## Project Layout
 
-- Java public API / JNI front door: `library/src/main/java/org/wysaid/nativePort/`
-  - `CGENativeLibrary`, `CGEImageHandler`, `CGEFrameRenderer`, `CGEFrameRecorder`
-- Native engine: `library/src/main/jni/cge/`
-- JNI bridge (Java ↔ C++): `library/src/main/jni/interface/`
-- Extension filters (built as `libCGEExt.so`): `library/src/main/jni/custom/`
-- Prebuilt FFmpeg variants: `library/src/main/jni/ffmpeg/` and `ffmpeg-16kb/`
-- Demo app (`cgeDemo/`) is for examples; avoid coupling new library APIs to demo-only code.
+| Path | Purpose |
+|------|---------|
+| `library/src/main/java/org/wysaid/nativePort/` | Public Java API (`CGENativeLibrary`, `CGEImageHandler`, etc.) |
+| `library/src/main/jni/cge/` | Core C++ engine |
+| `library/src/main/jni/interface/` | JNI bridge (Java ↔ C++) |
+| `library/src/main/jni/custom/` | Extension filters (`libCGEExt.so`) |
+| `library/src/main/jni/ffmpeg/`, `ffmpeg-16kb/` | Prebuilt FFmpeg variants |
+| `cgeDemo/` | Demo app — don't couple library APIs to demo-only code |
 
-## Build toggles you must respect
+## Build
 
-These flags come from `local.properties` (see `settings.gradle`):
+Use `tasks.sh` for all operations (`bash tasks.sh --help`). Key `local.properties` flags: `usingCMakeCompile`, `disableVideoModule`, `enable16kPageSizes`. See `docs/build.md` for details.
 
-- `usingCMakeCompile`: build native code via CMake; otherwise use prebuilt `.so` in `library/src/main/libs/`.
-- `usingCMakeCompileDebug`: toggles Debug vs Release native build.
-- `disableVideoModule`: when true, **no FFmpeg / no recording**.
-- `enable16kPageSizes`: enables 16KB page-size linking flags and uses `ffmpeg-16kb`.
-- `deployArtifacts`: enables maven publishing tasks.
+**Important**: CMake uses `GLOB_RECURSE`; ndk-build (`Android.mk`) lists sources **explicitly** — update both when adding native files.
 
-Important: CMake uses recursive globs, but **ndk-build (`Android.mk`) lists sources explicitly**. If you add native files that must compile in ndk-build mode, update `Android.mk` accordingly.
+## Code Conventions
 
-## Native/C++ conventions that matter here
+Language-specific rules live in `.github/instructions/` and are auto-applied by file path — see `cpp.instructions.md`, `java.instructions.md`, `jni-bridge.instructions.md`.
 
-- Follow `.clang-format` (Allman braces, 4 spaces, no tabs). Keep code in `namespace CGE {}`.
-- **No C++ exceptions** (compiled with `-fno-exceptions`). Use return values and log errors.
-- Use project logging macros: `CGE_LOG_INFO`, `CGE_LOG_KEEP`, `CGE_LOG_ERROR`.
-- Inline shader strings via `CGE_SHADER_STRING_PRECISION_H()` / `CGE_SHADER_STRING_PRECISION_M()`.
+For detailed standards, see `.github/CONTRIBUTING.md`.
 
-## Java/OpenGL thread rules (project-specific pitfalls)
+## Documentation
 
-- For `GLSurfaceView`-based classes, do GL operations on the GL thread via `queueEvent(...)`.
-- `NativeLibraryLoader` controls native library loading order; don’t unconditionally load FFmpeg when video module is disabled.
+- `docs/build.md` — Full build guide and configuration options
+- `README.md` — API usage, custom filters, and code samples
+- `.github/RELEASE.md` — Release process and versioning
+- `.github/CONTRIBUTING.md` — Contributing guidelines and code standards
 
-## Adding a new GPU filter / feature (minimal checklist)
+## Skills
 
-1. Implement the filter in `library/src/main/jni/custom/` (or `cge/filters/` if it’s core).
-2. Initialize shaders/uniforms in `init()`; handle compile/link failures without crashing.
-3. Ensure GL resources are released (programs/textures/FBOs) along the existing lifecycle.
-4. If the feature is exposed to Java, add/update JNI wrappers under `library/src/main/jni/interface/` and keep signatures stable.
-5. If it should be reachable from rule strings, update the parsing/registration in the native engine (don’t change existing syntax).
-6. Keep FFmpeg/video-dependent logic behind `disableVideoModule` / `CGE_USE_VIDEO_MODULE` guards.
+- **Submit PR:** Follow `.github/skills/pr-submit/SKILL.md` to create or update pull requests
+- **Review PR:** Follow `.github/skills/pr-review/SKILL.md` to review pull requests
 
-## Communication & docs
+## Behavior Constraints
 
-- Use **English** for code comments, commit messages, and PR descriptions.
-- Don’t add new “how to build” tutorials here—put long-form docs in `README.md` (this file should stay short).
+- **Validation:** After native code changes, ALWAYS run `bash tasks.sh --enable-cmake --build`.
+- **Commit Policy:** Only commit to feature branches, never force-push to `master`.
+- **Completeness:** Implement fully or request clarification — no TODOs in committed code.
+- **Dual Build:** When adding native files, update both `CMakeLists.txt` and `Android.mk`.
+- **Thread Safety:** Never call OpenGL ES functions outside the GL thread.

.github/instructions/cpp.instructions.md

@@ -1,9 +1,6 @@
 ---
 description: "Use when editing C++ native code. Covers CGE engine conventions, shader patterns, memory safety, and OpenGL ES resource management."
-applyTo:
-  - "library/src/main/jni/cge/**/*.{cpp,h,c}"
-  - "library/src/main/jni/custom/**/*.{cpp,h,c}"
-  - "library/src/main/jni/interface/**/*.{cpp,h,c}"
+applyTo: "library/src/main/jni/cge/**/*.cpp,library/src/main/jni/cge/**/*.h,library/src/main/jni/cge/**/*.c,library/src/main/jni/custom/**/*.cpp,library/src/main/jni/custom/**/*.h,library/src/main/jni/custom/**/*.c,library/src/main/jni/interface/**/*.cpp,library/src/main/jni/interface/**/*.h,library/src/main/jni/interface/**/*.c"
 ---
 
 # C++ / Native Layer

.github/instructions/java.instructions.md

@@ -1,8 +1,6 @@
 ---
 description: "Use when editing Java Android library or demo code. Covers GL thread safety and native interop patterns."
-applyTo:
-  - "library/src/main/java/**/*.java"
-  - "cgeDemo/src/main/java/**/*.java"
+applyTo: "library/src/main/java/**/*.java,cgeDemo/src/main/java/**/*.java"
 ---
 
 # Java / Android Layer

.github/skills/pr-review/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: pr-review
+description: Address review comments from GitHub PR using gh CLI and resolve feedback
+---
+
+## When to use
+
+- Current branch has a PR with review comments requiring responses
+- Need to systematically evaluate and resolve reviewer feedback
+
+## Constraints
+
+- **ALWAYS** set `PAGER=cat` before calling `gh` to avoid pagination issues
+- Use `gh pr view <PR_NUMBER> --comments` to fetch review comments
+- Use `gh pr list --head <CURRENT_BRANCH>` to find the PR number for the current branch
+
+## Procedure
+
+1. **Find Issues**: Use `gh` to locate the PR for current branch and retrieve all review comments
+2. **Evaluate**: Analyze each comment in project context:
+   - If valid: implement the necessary code improvements
+   - If invalid: document reasons and address any underlying real issues
+3. **Summarize**: Provide a summary covering:
+   - Valid points and how they were resolved
+   - Invalid points and reasons for rejection  
+   - Any additional issues discovered and fixed
+4. **Commit**: Generate commit message, then `git commit` and `git push`
+
+## Output
+
+- Clear mapping between review comments and their resolutions

.github/skills/pr-submit/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: pr-submit
+description: Create or update a GitHub Pull Request after completing code changes
+---
+
+## When to use
+
+- Code changes are complete and ready for review
+- Need to create a new PR or update an existing one with new commits
+
+## Constraints
+
+- **ALWAYS** set `PAGER=cat` before calling `gh` to avoid pagination issues
+
+## Procedure
+
+1. **Verify**: Review conversation history and current changes—ensure completeness, correctness, no performance issues
+2. **Clean**: Remove temporary files, debug artifacts, and unintended changes
+3. **Commit & Push**:
+   - If on `master`, create a new feature branch (avoid name conflicts)
+   - Commit all changes and push to remote
+4. **PR**: Use `gh` to create or update the Pull Request:
+   - Check if current branch has an existing PR
+   - **If exists**: Fetch title/description, incorporate new commits, update the PR
+   - **If not**: Create PR against remote `master`, draft title/description from changes
+
+## Output
+
+- Focus on: what changed, why, impact, verification

.github/workflows/macos-build.yml

@@ -4,7 +4,7 @@ on:
   push:
     branches:
       - "master"
-      - "*workflow*"
+      - "test_workflow*"
   pull_request:
     branches: [ "master" ]