diff --git a/docs/src/content/docs/commands/auth.md b/docs/src/content/docs/commands/auth.md
index ac0ffc19a..4354d768f 100644
--- a/docs/src/content/docs/commands/auth.md
+++ b/docs/src/content/docs/commands/auth.md
@@ -84,18 +84,18 @@ sentry auth refresh
 
 This is typically handled automatically when tokens expire.
 
-## Configuration
+## Credential Storage
 
-Credentials are stored in `~/.sentry/config.json` with restricted file permissions (mode 600).
+Credentials are stored in a SQLite database at `~/.sentry/cli.db` with restricted file permissions (mode 600).
 
-**Config structure:**
+Use `sentry auth token` to retrieve your current access token, or `sentry auth status` to check authentication state.
 
-```json
-{
-  "auth": {
-    "token": "...",
-    "refreshToken": "...",
-    "expiresAt": "2024-12-31T00:00:00Z"
-  }
-}
-```
+### Environment Variable Precedence
+
+The CLI checks for auth tokens in the following order, using the first one found:
+
+1. `SENTRY_AUTH_TOKEN` environment variable (legacy)
+2. `SENTRY_TOKEN` environment variable
+3. The stored token in the SQLite database
+
+When a token comes from an environment variable, the CLI skips expiry checks and automatic refresh.
diff --git a/docs/src/content/docs/configuration.md b/docs/src/content/docs/configuration.md
index 7e0efec24..49e986232 100644
--- a/docs/src/content/docs/configuration.md
+++ b/docs/src/content/docs/configuration.md
@@ -138,9 +138,11 @@ The `sentry api` command also uses `--verbose` to show full HTTP request/respons
 
 ## Credential Storage
 
-Credentials are stored in a SQLite database at `~/.sentry/` (or the path set by `SENTRY_CONFIG_DIR`) with restricted file permissions (mode 600) for security. The database also caches:
+We store credentials and caches in a SQLite database (`cli.db`) inside the config directory (`~/.sentry/` by default, overridable via `SENTRY_CONFIG_DIR`). The database file and its WAL side-files are created with restricted permissions (mode 600) so that only the current user can read them. The database also caches:
 
 - Organization and project defaults
 - DSN resolution results
 - Region URL mappings
 - Project aliases (for monorepo support)
+
+See [Credential Storage](./commands/auth/#credential-storage) in the auth command docs for more details.
diff --git a/src/commands/auth/logout.ts b/src/commands/auth/logout.ts
index 5565c3239..82b68e588 100644
--- a/src/commands/auth/logout.ts
+++ b/src/commands/auth/logout.ts
@@ -30,7 +30,7 @@ export const logoutCommand = buildCommand({
   docs: {
     brief: "Log out of Sentry",
     fullDescription:
-      "Remove stored authentication credentials from the configuration file.",
+      "Remove stored authentication credentials from the local database.",
   },
   output: { json: true, human: formatLogoutResult },
   parameters: {
diff --git a/src/lib/dsn/types.ts b/src/lib/dsn/types.ts
index a0f5040da..200ad8555 100644
--- a/src/lib/dsn/types.ts
+++ b/src/lib/dsn/types.ts
@@ -66,7 +66,7 @@ export type ResolvedProject = ResolvedProjectInfo & {
 /**
  * Cached DSN entry with full resolution info
  *
- * Stored in ~/.sentry/config.json under dsnCache[directory]
+ * Stored in ~/.sentry/cli.db in the dsn_cache table
  */
 export type CachedDsnEntry = {
   /** The raw DSN string */
diff --git a/src/lib/oauth.ts b/src/lib/oauth.ts
index 988fae206..c67701831 100644
--- a/src/lib/oauth.ts
+++ b/src/lib/oauth.ts
@@ -301,7 +301,7 @@ export async function performDeviceFlow(
 }
 
 /**
- * Complete the OAuth flow by storing the token in the config file.
+ * Complete the OAuth flow by storing the token in the database.
  *
  * @param tokenResponse - The token response from performDeviceFlow
  */