From ea1d89a2b87ca3bcd7367173509efb342e99c2fe Mon Sep 17 00:00:00 2001
From: v1ad3k <58193845+v1ad3k@users.noreply.github.com>
Date: Mon, 14 Sep 2026 18:22:55 +0500
Subject: [PATCH] docs(guides/postinstall): add troubleshooting reference for
 suspend freezes on modern kernels

---
 docs/guides/postinstall.md | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/docs/guides/postinstall.md b/docs/guides/postinstall.md
index 1c2d3916..0f9fd799 100644
--- a/docs/guides/postinstall.md
+++ b/docs/guides/postinstall.md
@@ -187,3 +187,10 @@ internal devices unavailable after resume.
 
 When migrating from apple-bce, remove any old suspend service or elogind hook
 that unloads it before testing suspend with t2bce.
+
+### Troubleshooting Persistent Suspend Freezes
+
+If your hardware configuration continues to experience sleep lockups, post-wake kernel panics, or Touch Bar / keyboard desync on modern kernels:
+
+- **[apple-t2-suspend-fix](https://github.com/v1ad3k/apple-t2-suspend-fix)**: A community systemd orchestration suite for modern kernels that manages pre-suspend driver teardown, CPU 0 IRQ pinning during wake transitions, Wi-Fi soft-sleep, and device reinitialization.
+