From 51c39f94cf919a2cd37d15ec3c4db475744776b0 Mon Sep 17 00:00:00 2001
From: John O'Keefe <jrokeefe@protonmail.com>
Date: Thu, 12 Feb 2026 10:58:39 -0500
Subject: [PATCH] docs: add documentation update checklist to implementation
 plan

- Add Section 16: Documentation Updates Required
- Detail specific line numbers and changes for koreader-setup.md:
  - Line 126: Change "Basic Auth" to "Bearer Token"
  - Lines 127-128: Remove username/password references
- Detail verification needed for kobo-setup.md:
  - Lines 37-53: Confirm no serial number references
  - Verify registration flow describes automatic token generation
- Update Phase 1 tasks with specific line number references
- Update Phase 2 Kobo documentation tasks with verification notes
---
 IMPLEMENTATION_PLAN.md | 67 +++++++++++++++++++++++++++++++++++++-----
 1 file changed, 60 insertions(+), 7 deletions(-)

diff --git a/IMPLEMENTATION_PLAN.md b/IMPLEMENTATION_PLAN.md
index 1a31499..998c213 100644
--- a/IMPLEMENTATION_PLAN.md
+++ b/IMPLEMENTATION_PLAN.md
@@ -274,6 +274,8 @@ func (m *DeviceAuthMiddleware) Authenticate(next echo.HandlerFunc) echo.HandlerF
     - [ ] Security warning about API keys in logs
     - [ ] Network security recommendations (VPN, local network)
     - [ ] Instructions for regenerating token if compromised
+    - **Note**: Documentation was updated on 2026-02-12 to reflect API key authentication
+    - **Verification**: Confirm lines 37-53 don't reference entering serial number (device registration generates token automatically)
 
 2. **Kobo Sync Validation** (`cmd/server/tests/kobo_test.go`)
     - [ ] Update tests to use API key in URL path
@@ -978,6 +980,46 @@ This implementation plan emerged from a detailed analysis of the current authent
 
 ---
 
+## 16. Documentation Updates Required (Pre-Implementation Checklist)
+
+Based on codebase analysis, the following documentation updates are needed:
+
+### koreader-setup.md (docs/user/devices/koreader-setup.md)
+**Current Issues:**
+- Line 126: Says "Basic Auth" - should be "Bearer Token"
+- Lines 127-128: Reference username/password - should reference auth_token
+- Documentation states KOReader uses Basic Auth (incorrect)
+
+**Required Changes:**
+```diff
+- 1. **Authentication Method**: Select "Basic Auth"
+- 2. **Username**: Your Bookhoard email or username
+- 3. **Password**: Your Bookhoard password
++ 1. **Authentication Method**: Bearer Token (API Key)
++ 2. **Auth Token**: Copy from Bookhoard Device Management page
++ 3. **Setup**: Plugin will include token in Authorization header automatically
+```
+
+### kobo-setup.md (docs/user/devices/kobo-setup.md)
+**Current Status:**
+- Updated on 2026-02-12 to reflect API key authentication
+- Shows full URL format with token
+
+**Verification Needed:**
+- Confirm lines 37-53 (device registration) don't mention entering serial number
+- Verify registration flow describes automatic API key generation
+- Ensure "Copy Full Sync URL" button is documented
+
+### New Documentation: security.md
+**Required Content:**
+- API key in URL path security considerations
+- Comparison: API key (URL) vs Bearer token (header)
+- Network security recommendations (HTTPS, VPN, local-only)
+- Token regeneration best practices
+- Risk mitigations for self-hosted deployments
+
+---
+
 ## 10. Risk Assessment
 
 **Low Risk:**
@@ -1204,15 +1246,26 @@ http://IP:8765/opds/devices/{DEVICE_ID}/catalog
    - Return new token to user
 
 4. **[CRITICAL]** Update kobo-setup.md documentation:
-   - Remove Username/Password references (lines 116-118)
-   - Explain API key in URL configuration
-   - Show full URL with token: `http://IP:8765/api/sync/kobo/{API_KEY}`
-   - Document token regeneration process
+    - Remove Username/Password references (if any remain)
+    - Verify registration flow reflects API key generation:
+      - Device registration automatically generates `auth_token`
+      - User copies full sync URL from device management page (not just token)
+      - Example: `http://IP:8765/api/sync/kobo/{API_KEY}`
+    - Explain API key in URL configuration
+    - Show full URL with token: `http://IP:8765/api/sync/kobo/{API_KEY}`
+    - Document token regeneration process
+    - **Status**: Documentation was updated on 2026-02-12 to reflect API key auth
+    - **Verification Needed**: Ensure no references to entering serial number remain (lines 37-53)
 
 5. **[CRITICAL]** Update koreader-setup.md documentation:
-   - Change "Basic Auth" to "Bearer Token" authentication
-   - Remove incorrect username/password references (lines 26-27)
-   - Explain plugin token management
+    - Change "Basic Auth" to "Bearer Token" authentication (line 126)
+    - Remove incorrect username/password references (lines 127-128)
+      - Currently: "Username: Your Bookhoard email or username"
+      - Currently: "Password: Your Bookhoard password"
+      - Should be: "Auth Token: Your device API key from Bookhoard"
+    - Explain plugin token management
+    - **Note**: Current docs mention "Basic Auth" which is INCORRECT
+    - **Note**: KOReader uses Bearer token in Authorization header (not Basic Auth)
 
 6. **[TESTING]** Update test coverage:
    - Test Kobo sync with API key in URL path