Document design decisions; update plan to reflect dropped jwt.ts

AGENTS.md

@@ -158,6 +158,10 @@ Model: <display_model>
 | Pi extension system overview | `docs/pi_docs_extension.md` |
 | Pi platform reference (SDK, RPC, sessions, settings, packages) | `docs/pi_platform_reference.md` |
 
+## Design Decisions
+
+See `docs/design-decisions.md` for rationale on non-obvious choices.
+
 ## Common Gotchas
 
 - `Type.Union([Type.Literal("a"), ...])` does NOT work for Google models — use `StringEnum` from `@mariozechner/pi-ai`

docs/design-decisions.md

@@ -0,0 +1,9 @@
+# Design Decisions
+
+## AUTH errors do not auto-clear the cached token
+
+When Perplexity returns 401/403 and `SearchError("AUTH")` is thrown, `src/index.ts` returns an error message directing the user to run `/perplexity-login --force`. It does **not** call `clearToken()` automatically.
+
+**Rationale:** A 401 can be transient — network blip, Cloudflare hiccup, clock skew. Auto-clearing on every 4xx would silently discard a still-valid token and force unnecessary re-authentication. The user decides when to re-login. `/perplexity-login --force` clears and re-authenticates in one explicit step.
+
+The token is only cleared when the user explicitly requests it (`--force`) or calls `clearToken()` directly (e.g. in tests or future tooling).

plan.md

@@ -99,13 +99,11 @@ export default factory;
 
 ## Phase 2: Auth — JWT Acquisition and Storage
 
-### 2.1 JWT utilities (`src/auth/jwt.ts`)
+### 2.1 ~~JWT utilities (`src/auth/jwt.ts`)~~ — dropped
 
-Implement:
-- `decodeJwtExpiry(token: string): number` — base64url decode payload, extract `exp` claim, return ms with 5-min margin. Fallback: now + 1 hour.
-- `isJwtExpired(token: string, bufferMs?: number): boolean`
-
-No dependencies. Use `atob` or `Buffer.from(payload, "base64url")`.
+Proactive expiry checking was dropped in favour of reactive re-auth: on HTTP 401/403
+the tool returns an error directing the user to run `/perplexity-login --force`.
+See `docs/design-decisions.md` for rationale.
 
 ### 2.2 Token storage (`src/auth/storage.ts`)