From a01f0681a03844616dd056c2b7455d0e373c0ee6 Mon Sep 17 00:00:00 2001
From: Ivan Pereira <183991+ivanrvpereira@users.noreply.github.com>
Date: Mon, 23 Feb 2026 10:49:49 +0000
Subject: [PATCH] Document design decisions; update plan to reflect dropped
 jwt.ts

---
 AGENTS.md                |  4 ++++
 docs/design-decisions.md |  9 +++++++++
 plan.md                  | 10 ++++------
 3 files changed, 17 insertions(+), 6 deletions(-)
 create mode 100644 docs/design-decisions.md

diff --git a/AGENTS.md b/AGENTS.md
index ae4eec5..a18046d 100644
--- a/AGENTS.md
+++ b/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`
diff --git a/docs/design-decisions.md b/docs/design-decisions.md
new file mode 100644
index 0000000..4d21bae
--- /dev/null
+++ b/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).
diff --git a/plan.md b/plan.md
index a77f91e..d4ff48b 100644
--- a/plan.md
+++ b/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`)