feat: store auth tokens in OS credential storage (#77)

Author: gnapse

README.md

@@ -26,12 +26,41 @@ This makes the `tw` command available globally.
 
 ## Setup
 
-Set up your Twist API token:
-
 ```bash
 tw auth login
 ```
 
+This opens your browser to authenticate with Twist. Once approved, the token is stored in your OS credential manager:
+
+- macOS: Keychain
+- Windows: Credential Manager
+- Linux: Secret Service/libsecret
+
+If secure storage is unavailable, the CLI warns and falls back to `~/.config/twist-cli/config.json`. Existing plaintext tokens are migrated automatically the next time the CLI reads them successfully from the config file. Non-secret settings such as the current workspace remain in the config file.
+
+### Alternative methods
+
+**Manual token:**
+
+```bash
+tw auth token "your-token"
+```
+
+**Environment variable:**
+
+```bash
+export TWIST_API_TOKEN="your-token"
+```
+
+`TWIST_API_TOKEN` always takes priority over the stored token.
+
+### Auth commands
+
+```bash
+tw auth status   # check if authenticated
+tw auth logout   # remove saved token
+```
+
 ## Usage
 
 ```bash

docs/SPEC.md

@@ -50,7 +50,9 @@ __tests__/                   # Test suite
 Token resolution (priority order):
 
 1. Environment variable: `TWIST_API_TOKEN`
-2. Config file: `~/.config/twist-cli/config.json`
+2. System credential manager (Keychain, Credential Manager, or Secret Service)
+3. Legacy plaintext token in `~/.config/twist-cli/config.json` during auto-migration
+4. Plaintext config fallback when the OS credential store is unavailable
 
 ## Workspace Scoping
 
@@ -469,11 +471,12 @@ Location: `~/.config/twist-cli/config.json`
 
 ```json
 {
-  "token": "optional-token-here",
   "currentWorkspace": 12345
 }
 ```
 
+`token` may appear temporarily in legacy installs before migration, or as a fallback when the system credential manager is unavailable.
+
 ---
 
 ## Examples

package-lock.json

@@ -70,5 +70,8 @@
         "semantic-release": "25.0.3",
         "typescript": "5.9.3",
         "vitest": "4.0.18"
+    },
+    "optionalDependencies": {
+        "@napi-rs/keyring": "1.2.0"
     }
 }