Clarify dedicated agent token guidance (#1353)

docs/UNIFIED_AGENT.md

@@ -178,6 +178,8 @@ These flags are accepted by the `pulse-agent` binary directly but are **not** av
 
 **Token resolution order**: `--token` → `--token-file` → `PULSE_TOKEN` → `/var/lib/pulse-agent/token`.
 
+Use one dedicated API token per host or VM installation. Reuse a token only when multiple agents intentionally share one logical identity, such as a Kubernetes DaemonSet configured with `PULSE_AGENT_ID`.
+
 ### Advanced Flags
 
 - `--version`: Print the agent version and exit.

frontend-modern/src/components/Settings/UnifiedAgents.tsx

@@ -1017,6 +1017,9 @@ export const UnifiedAgents: Component = () => {
                                 <p class="text-sm text-gray-600 dark:text-gray-400 ml-6">
                                     Create a fresh token scoped for Host, Docker, and Kubernetes monitoring.
                                 </p>
+                                <p class="text-xs text-gray-500 dark:text-gray-400 ml-6">
+                                    Use one dedicated token per host or VM installation. Only reuse a token when multiple agents intentionally share one identity, such as a Kubernetes DaemonSet with <code>PULSE_AGENT_ID</code>.
+                                </p>
                             </div>
 
                             <div class="flex gap-2">
@@ -1051,6 +1054,9 @@ export const UnifiedAgents: Component = () => {
                                         Token <strong>{latestRecord()?.name}</strong> created. Commands below now include this credential.
                                     </span>
                                 </div>
+                                <p class="text-xs text-blue-700 dark:text-blue-300 ml-6">
+                                    Install this token on one machine only. Generate another token for the next host unless you are deliberately using a shared identity.
+                                </p>
                             </Show>
 
                         </div>

frontend-modern/src/components/Settings/__tests__/UnifiedAgents.test.tsx

@@ -204,6 +204,7 @@ describe('UnifiedAgents token generation', () => {
       expect(screen.getByText('Generate API token')).toBeInTheDocument();
     });
     expect(screen.getByRole('button', { name: /Generate token/i })).toBeInTheDocument();
+    expect(screen.getByText(/Use one dedicated token per host or VM installation/i)).toBeInTheDocument();
   });
 
   it('generates a token and shows confirmation', async () => {
@@ -232,6 +233,7 @@ describe('UnifiedAgents token generation', () => {
       () => expect(screen.getByText(/Token.*created/i)).toBeInTheDocument(),
       { interval: 0 },
     );
+    expect(screen.getByText(/Install this token on one machine only/i)).toBeInTheDocument();
     expect(notificationSuccessMock).toHaveBeenCalledWith(
       'Token generated with Host config + reporting, Docker, and Kubernetes permissions.',
       4000,