1 files changed, 17 insertions, 47 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 788425e..7e31c97 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,57 +1,27 @@
 # Contributing
 
-YASL focuses on desktop surfaces for applications that own their renderer.
-Read the [API policy](docs/api-policy.md) and [application guide](docs/guide.md)
-before changing public behavior. Keep backend details in native extensions and
-make common operations usable through the portable headers.
+YASL is a small desktop surface/input library for application-owned loops and
+renderers. Read [the guide](docs/guide.md) and [API policy](docs/api-policy.md).
+Keep public C APIs direct: opaque surface pointers, plain IDs/numeric arguments,
+and one tagged event. Avoid new descriptor/geometry/string/handle helper structs,
+application runners, graphics engines, or hidden presentation policy.
 
-Shared API behavior and backend interfaces live in `src/common/`. Native
-windowing implementations, key mappings, and typed native accessors live in
-`src/platform/<backend>/`; keep their generated protocols with the backend.
-OS support shared by multiple backends lives separately in `src/platform/posix/`
-and is selected by `src/platform/meson.build`. It currently supplies the event
-loop and the private mutex implementation used through `platform/sync.h`.
-Linux desktop services shared by Wayland and X11, such as xdg-open and the
-D-Bus session bus, live in `src/platform/freedesktop/`; Cocoa keeps its own in
-`src/platform/cocoa/desktop.m`. Both implement `src/common/desktop.h`.
-Common code should depend on these internal interfaces rather than native OS
-headers. Keep public headers in `include/yasl/` and tests in `tests/<backend>/`.
+Portable lifetime, event ownership, validation, and rendering bridges live in
+src/common. Native implementations live in src/platform/wayland, x11, and cocoa.
+Private backend geometry/frame/loop types are implementation details, not installed
+API. Linux desktop services live in src/platform/freedesktop; POSIX synchronization
+and waiting live in src/platform/posix. Keep native handles typed in extension headers.
 
-For a future Win32 backend, add `src/platform/win32/`, select its event loop and
-`yasl_platform_sync.h` in the platform build, and register its backend through
-the common dispatch interface. Windows still needs build/dependency selection,
-public API/export support, and ports of POSIX-based examples and test harnesses;
-the directory structure alone does not provide Windows support.
-
-For a bug report, include the revision, operating system, selected backend from
-`yasl_display_backend()`, capability mask, compiler, build options, reproduction
-steps, and a small example if possible. For input issues include the relevant
-event fields, layout/device/driver, and whether the issue occurs on another
-backend. Report observations separately from expected behavior.
-
-Build and test with:
+Document public units, ownership, errors, thread requirements, callback timing,
+and unsupported behavior. Add useful behavior coverage and examples. Run:
 
 ```sh
-meson setup build
 meson compile -C build
 meson test -C build --print-errorlogs
 ```
 
-See [testing](docs/testing.md) for isolated Linux integration tests, sanitizer
-builds, and native tablet tests. Changes to shared behavior need both backend
-configurations checked. Cocoa changes need a macOS desktop build/test; Linux
-success alone does not validate them. Keep changes focused and describe any
-platforms that were not exercised.
-
-Document public behavior in the public header first: argument validity,
-units, ownership/lifetime, return/error behavior, thread requirements, callback
-rules, and unsupported results. Update guides/examples when the workflow
-changes. Use zero-initialized specs and check fallible operations in examples.
-Build the reference with `doxygen Doxyfile`; warnings are errors. Do not edit
-vendored generated protocol files for unrelated changes.
-
-Use the existing C style and `yasl_`/`YASL_` public names. Run the tests relevant
-to the changed behavior, including shared exports and public C/C++ compilation.
-For a pull request, explain the observable problem, resulting behavior, and
-validation, including any native tests still needed. Contributions use the
-project's MIT license.
+Changes to portable/native behavior need both Linux backends and installed shared/
+static consumers checked. Use the isolated GPU suite described in [testing](docs/testing.md).
+Cocoa changes require a native macOS build/test; disclose platforms not exercised.
+Do not edit generated protocol files for unrelated changes. Check exact exports and
+public C/C++ compilation. Contributions use the project's MIT license.