Add known issue for osquery integration failure on macOS [#1528]

release-notes/fleet-elastic-agent/index.md

@@ -30,8 +30,6 @@ To check for security updates, go to [Security announcements for the Elastic sta
 
 ### Features and enhancements [fleet-elastic-agent-9.0.2-features-enhancements]
 
-fleet-server::
-
 * Updates Go version to v1.24.3 in {{fleet}} [#4891]({{fleet-server-pull}}4891)
 
 * Updates Go version to v1.24.3 in {{agent}} [#8109]({{agent-pull}}8109)

release-notes/fleet-elastic-agent/known-issues.md

@@ -15,6 +15,63 @@ Known issues are significant defects or limitations that may impact your impleme
 % **Workaround** 
 % Workaround description.
 
-:::
+% :::
 
-_No known issues_
+:::{dropdown} [macOS] Osquery integration fails to start on fresh agent installs
+
+**Applies to: {{agent}} 9.0.0 and 9.0.1 (macOS only)**
+
+On May 26th, 2025, a known issue was discovered that causes the `osquery` integration to fail on new {{agent}} installations on macOS. During the installation process, the required `osquery.app/` directory is removed, which prevents the integration from starting.
+
+For more information, check [Issue #8245](https://github.com/elastic/elastic-agent/issues/8245).
+
+**Workaround** 
+
+As a workaround, you can manually restore the `osquery.app/` directory as follows:
+
+1. Extract the {{agent}} package, but do not install it yet.
+
+2. Open the following file in the extracted directory:
+
+   ```
+   data/elastic-agent-68f3ed/components/agentbeat.spec.yml
+   ```
+
+3. Locate the `component_files` section at the top of the file. It should look similar to this:
+
+   ```yaml
+   version: 2
+   component_files:
+     - certs/*
+     - lenses/*
+     - module/*
+     - "osquery-extension.ext"
+     - "osquery-extension.exe"
+     - osqueryd
+     - "osqueryd.exe"
+   ```
+
+4. Add the following entry to the end of the list:
+
+   ```yaml
+     - "osquery.app/*"
+   ```
+
+   The updated section should now look like this:
+
+   ```yaml
+   version: 2
+   component_files:
+     - certs/*
+     - lenses/*
+     - module/*
+     - "osquery-extension.ext"
+     - "osquery-extension.exe"
+     - osqueryd
+     - "osqueryd.exe"
+     - "osquery.app/*"
+   ```
+
+5. Proceed to install {{agent}} from the extracted directory as usual.
+
+:::