diff --git a/.cursor/rules/docs.mdc b/.cursor/rules/docs.mdc
index c72cf439..2af4c24b 100644
--- a/.cursor/rules/docs.mdc
+++ b/.cursor/rules/docs.mdc
@@ -14,7 +14,7 @@ knows nothing about our internal architecture.
 
 - Lead with what the user needs to provide (inputs), what they call, and what
   they get back. A reader should be able to run the thing from the intro alone.
-- State prerequisites explicitly (e.g. must be logged in with `deeporigin login`,
+- State prerequisites explicitly (e.g. must be authenticated — link `docs/how-to/auth.md`,
   whether a call blocks, what type is returned).
 
 # Do NOT use internal jargon
diff --git a/.cursor/rules/python.mdc b/.cursor/rules/python.mdc
index f30ac5d6..a000576f 100644
--- a/.cursor/rules/python.mdc
+++ b/.cursor/rules/python.mdc
@@ -61,7 +61,7 @@ When shipping a new user-facing SDK capability in the cli repo, include all of t
 1. Implementation following code style
 2. Tests in `tests/` that verify the behavior (mock server routes when needed)
 3. Documentation in `docs/` (API reference and/or how-to as appropriate)
-4. **Demo notebook** — never create or edit notebooks in `docs/notebooks/clean/` directly. Write `docs/notebooks/dirty/{feature}.ipynb` (gitignored; agents can still create it). After it runs against a live org (`deeporigin login`, `DeepOriginClient.from_disk()`), promote with `./scripts/notebooks.sh` (dirty → clean, strip outputs). The committed artifact is `docs/notebooks/clean/{feature}.ipynb`.
+4. **Demo notebook** — never create or edit notebooks in `docs/notebooks/clean/` directly. Write `docs/notebooks/dirty/{feature}.ipynb` (gitignored; agents can still create it). After it runs against a live org (authenticated per `docs/how-to/auth.md`, `DeepOriginClient.from_disk()`), promote with `./scripts/notebooks.sh` (dirty → clean, strip outputs). The committed artifact is `docs/notebooks/clean/{feature}.ipynb`.
 
 # Common mistakes
 
diff --git a/docs/dd/tools/enumerator.md b/docs/dd/tools/enumerator.md
index 2763594a..8fbde006 100644
--- a/docs/dd/tools/enumerator.md
+++ b/docs/dd/tools/enumerator.md
@@ -11,8 +11,8 @@ To run it you need:
   ([MMP :octicons-link-external-16:](https://en.wikipedia.org/wiki/Matched_molecular_pair_analysis)) modes)
 
 Create an `Enumerator`, call `run()`, and get a `pandas.DataFrame` of results
-back. `run()` blocks until the job finishes, so you must be logged in
-(`deeporigin login`) before calling it.
+back. `run()` blocks until the job finishes, so you must be
+[authenticated](../../how-to/auth.md) before calling it.
 
 ## Modes
 
diff --git a/docs/dd/tools/structure-report.md b/docs/dd/tools/structure-report.md
index 135721fb..f11ed0dd 100644
--- a/docs/dd/tools/structure-report.md
+++ b/docs/dd/tools/structure-report.md
@@ -6,7 +6,7 @@ Grade a protein structure for target preparation. Provide a local
 ID, or both. Call `run()` to get letter grades and component scores from the
 platform — the client does not recompute grades.
 
-You must be logged in (`deeporigin login`) before calling `run()`. The call
+You must be [authenticated](../../how-to/auth.md) before calling `run()`. The call
 blocks until the job finishes.
 
 ## Local structure
diff --git a/docs/dd/tools/uniprot-discovery.md b/docs/dd/tools/uniprot-discovery.md
index a8e33e61..191687cd 100644
--- a/docs/dd/tools/uniprot-discovery.md
+++ b/docs/dd/tools/uniprot-discovery.md
@@ -7,7 +7,7 @@ structures. Call `run()` to browse candidates (letter grades and scores from the
 platform). Call `import_proteins()` to download selected (or recommended) PDBs
 and sync them into a project with `uniprot_accession` set.
 
-You must be logged in (`deeporigin login`) before calling `run()` or
+You must be [authenticated](../../how-to/auth.md) before calling `run()` or
 `import_proteins()`. Those calls block until the job finishes. Import requires a
 project id (pass `project_id=...` or set it on the client).
 
diff --git a/docs/notebooks/clean/admet.ipynb b/docs/notebooks/clean/admet.ipynb
index 0fccca05..5d4b5918 100644
--- a/docs/notebooks/clean/admet.ipynb
+++ b/docs/notebooks/clean/admet.ipynb
@@ -13,7 +13,7 @@
     "**Run modes**\n",
     "\n",
     "- **Local mock:** set `DO_ENV=local` and start the mock server (`make mock-server`).\n",
-    "- **Dev:** set `DO_ENV=dev` after `deeporigin login`.\n",
+    "- **Dev:** set `DO_ENV=dev` after [authenticating](../../how-to/auth.md).\n",
     "\n",
     "Toggle `TARGET_ENV` below and re-run all cells."
    ]
diff --git a/docs/notebooks/clean/constrained-docking.ipynb b/docs/notebooks/clean/constrained-docking.ipynb
index 81d0fcdd..0ce8fd02 100644
--- a/docs/notebooks/clean/constrained-docking.ipynb
+++ b/docs/notebooks/clean/constrained-docking.ipynb
@@ -35,7 +35,7 @@
     "server-side from a **reference ligand** identity and a required **reference\n",
     "pose** SDF.\n",
     "\n",
-    "Prerequisites: `deeporigin login` and a registered `deeporigin.constrained-docking`\n",
+    "Prerequisites: [authentication](../../how-to/auth.md) and a registered `deeporigin.constrained-docking`\n",
     "tool on your org."
    ]
   },
diff --git a/docs/notebooks/clean/entity-updates.ipynb b/docs/notebooks/clean/entity-updates.ipynb
index 393da468..78cb910d 100644
--- a/docs/notebooks/clean/entity-updates.ipynb
+++ b/docs/notebooks/clean/entity-updates.ipynb
@@ -33,7 +33,7 @@
    "source": [
     "## Setup\n",
     "\n",
-    "Credentials come from **`~/.deeporigin/`** (run `deeporigin login` once). We use `DeepOriginClient.from_disk()` so a repo `.env` or `DO_*` variables in the kernel do not override disk config."
+    "Credentials come from **`~/.deeporigin/`** (written when [authenticating](../../how-to/auth.md)). We use `DeepOriginClient.from_disk()` so a repo `.env` or `DO_*` variables in the kernel do not override disk config."
    ]
   },
   {
@@ -48,7 +48,7 @@
     "from deeporigin.drug_discovery import BRD_DATA_DIR, Ligand, Protein\n",
     "from deeporigin.platform import DeepOriginClient\n",
     "\n",
-    "# Disk config only (~/.deeporigin/ after `deeporigin login`).\n",
+    "# Disk config only (~/.deeporigin/ after authenticating).\n",
     "# Do not use DeepOriginClient() here — it prefers DO_* env vars over disk.\n",
     "client = DeepOriginClient.from_disk(\"dev\")\n",
     "client"
diff --git a/docs/notebooks/clean/interactive-docking-box.ipynb b/docs/notebooks/clean/interactive-docking-box.ipynb
index 12003a41..cf59e906 100644
--- a/docs/notebooks/clean/interactive-docking-box.ipynb
+++ b/docs/notebooks/clean/interactive-docking-box.ipynb
@@ -178,7 +178,7 @@
     "## Run docking (platform)\n",
     "\n",
     "Adjust the box above first, then re-run the inspect cells to confirm the geometry.\n",
-    "Requires `deeporigin login` and a billing-enabled org."
+    "Requires being [authenticated](../../how-to/auth.md) and a billing-enabled org."
    ]
   },
   {
diff --git a/docs/notebooks/clean/molstar-protein-view.ipynb b/docs/notebooks/clean/molstar-protein-view.ipynb
index 2186cc06..d02ed5b5 100644
--- a/docs/notebooks/clean/molstar-protein-view.ipynb
+++ b/docs/notebooks/clean/molstar-protein-view.ipynb
@@ -105,7 +105,7 @@
    "source": [
     "## 3. `PreparedSystem.show()` — requires platform login\n",
     "\n",
-    "Run after `deeporigin login` if you have a prepared system result to visualize.\n",
+    "Run after [authenticating](../../how-to/auth.md) if you have a prepared system result to visualize.\n",
     "Skip this cell if you only want to verify the HTML builder and `Protein.show()`."
    ]
   },
diff --git a/docs/notebooks/clean/pocket-box-inferred-orientation.ipynb b/docs/notebooks/clean/pocket-box-inferred-orientation.ipynb
index 649a48f7..6d4af72e 100644
--- a/docs/notebooks/clean/pocket-box-inferred-orientation.ipynb
+++ b/docs/notebooks/clean/pocket-box-inferred-orientation.ipynb
@@ -9,7 +9,7 @@
     "\n",
     "Manual verification notebook for [DDOS-7327](https://deeporigin.atlassian.net/browse/DDOS-7327).\n",
     "\n",
-    "Run against **dev** (`DO_ENV=dev`, `deeporigin login`). Requires pocket-finder\n",
+    "Run against **dev** (`DO_ENV=dev`, [authenticated](../../how-to/auth.md)). Requires pocket-finder\n",
     "**1.6.19+** with nested `box` output (PCA OBB sizes + `rotation_deg`).\n",
     "\n",
     "Flow:\n",
diff --git a/docs/notebooks/clean/poses-vs-ligands-phase2.ipynb b/docs/notebooks/clean/poses-vs-ligands-phase2.ipynb
index 2b47e50b..65ccbbc0 100644
--- a/docs/notebooks/clean/poses-vs-ligands-phase2.ipynb
+++ b/docs/notebooks/clean/poses-vs-ligands-phase2.ipynb
@@ -9,7 +9,7 @@
     "\n",
     "This notebook compares **legacy pose-hydrated `Ligand` objects** with the new first-class **`Pose` / `PoseSet`** types.\n",
     "\n",
-    "Run against the local mock server or a dev org after `deeporigin login`.\n",
+    "Run against the local mock server or a dev org after [authenticating](../../how-to/auth.md).\n",
     "\n",
     "**Phase 2 scope:** additive API only. `Docking.get_poses()` still returns `LigandSet` until DDOS-6737."
    ]
diff --git a/src/platform/client.py b/src/platform/client.py
index e4f0617f..0c214c10 100644
--- a/src/platform/client.py
+++ b/src/platform/client.py
@@ -861,7 +861,7 @@ def from_disk(
         """Create a client from ``~/.deeporigin/`` config files.
 
         Use this for interactive work in Jupyter notebooks or CLI sessions where
-        credentials are stored on disk after running ``deeporigin login``.
+        credentials are stored on disk after authenticating.
 
         Environment selection order: explicit ``env`` parameter → value in
         ``~/.deeporigin/config.json``. ``"local"`` uses the toolbox gateway at