diff --git a/docs/public/llms-full.txt b/docs/public/llms-full.txt
index 3af4e10a..3d166931 100644
--- a/docs/public/llms-full.txt
+++ b/docs/public/llms-full.txt
@@ -2890,7 +2890,7 @@ Authenticate with GitHub to access Archgate editor plugins. If you are not regis
 archgate login
 ```
 
-Starts a GitHub Device Flow (OAuth). The CLI displays a one-time code and a URL. Open the URL in your browser, enter the code, and authorize the Archgate GitHub OAuth App. Once authorized, the CLI exchanges your GitHub identity for an Archgate plugin token and stores both in `~/.archgate/credentials`.
+Starts a GitHub Device Flow (OAuth). The CLI displays a one-time code and a URL. Open the URL in your browser, enter the code, and authorize the Archgate GitHub OAuth App. Once authorized, the CLI exchanges your GitHub identity for an Archgate plugin token and stores it securely in your OS credential manager (macOS Keychain, Windows Credential Manager, or Linux libsecret) via `git credential approve`. Non-sensitive metadata (username, date) is saved to `~/.archgate/credentials`.
 
 If your GitHub account is not yet registered, the CLI prompts for your email, preferred editor, and use case, then signs you up automatically.
 
@@ -2924,12 +2924,14 @@ and enter the code: ABCD-1234
 Waiting for authorization...
 GitHub user: yourname
 
-No account found. Let's get you signed up.
+Your GitHub account yourname is not yet registered.
+Let's sign you up now.
+
 Email: you@example.com
 Editor: Claude Code
 Use case: Enforcing ADRs in our monorepo
 
-Registering...
+Submitting signup request...
 Claiming archgate plugin token...
 
 Authenticated as yourname. Plugin access is now available.
@@ -3067,7 +3069,7 @@ Use `archgate plugin` to install plugins or retrieve the authenticated repositor
 
 #### archgate plugin url
 
-Print the authenticated plugin repository URL for manual tool configuration.
+Print the plugin repository URL for manual tool configuration.
 
 ```bash
 archgate plugin url [options]
@@ -3077,7 +3079,7 @@ archgate plugin url [options]
 | ------------------- | -------- | ------------------------------------------------------- |
 | `--editor <editor>` | `claude` | Target editor (`claude`, `cursor`, `vscode`, `copilot`) |
 
-The URL includes your credentials and can be used to manually configure editor tools. For example, to add the Archgate marketplace in Claude Code:
+The URL can be used to manually configure editor tools. Credentials are provided automatically by your git credential manager (stored during `archgate login`). For example, to add the Archgate marketplace in Claude Code:
 
 ```bash
 claude plugin marketplace add "$(archgate plugin url)"
diff --git a/src/helpers/credential-store.ts b/src/helpers/credential-store.ts
index 3a562231..abcbf637 100644
--- a/src/helpers/credential-store.ts
+++ b/src/helpers/credential-store.ts
@@ -19,7 +19,7 @@
 
 import { chmodSync, unlinkSync } from "node:fs";
 
-import { logDebug } from "./log";
+import { logDebug, logWarn } from "./log";
 import { internalPath, createPathIfNotExists } from "./paths";
 
 const CREDENTIAL_HOST = "plugins.archgate.dev";
@@ -186,7 +186,10 @@ export async function saveCredentials(
     logDebug("git credential approve failed — token may not be persisted");
   }
 
-  // Store metadata in ~/.archgate/credentials (for `login status` display)
+  // Store metadata in ~/.archgate/credentials (for `login status` display).
+  // DEPRECATED: The token is also written to this file as a fallback for systems
+  // without a git credential manager. In the next major version, only metadata
+  // (github_user, created_at) will be written — the token field will be removed.
   createPathIfNotExists(internalPath());
   const filePath = metadataPath();
   await Bun.write(filePath, JSON.stringify(credentials, null, 2) + "\n");
@@ -229,8 +232,15 @@ export async function loadCredentials(): Promise<StoredCredentials | null> {
     };
   }
 
-  // Fall back to token in the file (legacy plaintext storage)
+  // DEPRECATED: Fall back to token in the plaintext file (legacy storage).
+  // This fallback will be removed in the next major version. Users on systems
+  // without a git credential manager should run `archgate login refresh` to
+  // migrate their token to the credential manager.
   if (!data.token) return null;
+  logWarn(
+    "Token loaded from plaintext file (deprecated).",
+    "Run `archgate login refresh` to migrate to secure credential storage."
+  );
   return data;
 }