diff --git a/.clangd b/.clangd
new file mode 100644
index 0000000..87eea78
--- /dev/null
+++ b/.clangd
@@ -0,0 +1,27 @@
+# clangd configuration.
+#
+# `linux/runner/` is the GTK host program Flutter generates for the Linux
+# desktop target. It is stock scaffolding — unmodified since `flutter create` —
+# and it builds correctly on a Linux machine with the GTK development headers
+# installed.
+#
+# On macOS and Windows those headers do not exist, so clangd cannot resolve
+# `#include <gtk/gtk.h>`. Everything downstream then collapses: `MyApplication`,
+# `my_application_new` and `g_autoptr` are all produced by the
+# `G_DECLARE_FINAL_TYPE` macro, which never expands, so the editor reports a
+# handful of undeclared identifiers and an unused include on a six-line file
+# that has nothing wrong with it.
+#
+# Those are editor diagnostics, not build errors. `flutter build linux` on a
+# Linux box compiles this unchanged; nothing in the Flutter toolchain reads
+# clangd. Suppressing them here keeps the noise out of the problems panel
+# without touching generated code that the Linux build depends on.
+#
+# If you do want real analysis of this directory, do it on Linux with the GTK
+# headers present and a compile_commands.json — not by editing the runner.
+If:
+  PathMatch: linux/.*
+
+Diagnostics:
+  Suppress: '*'
+  UnusedIncludes: None