From 246d49cf547442fbcd8bd9cc4a79b57620cd9aa3 Mon Sep 17 00:00:00 2001
From: servius <servius@darksailor.dev>
Date: Thu, 30 Apr 2026 15:51:19 +0530
Subject: [PATCH] feat: Update agents.md

---
 AGENTS.md | 23 ++++++++++++++++++++++-
 CLAUDE.md |  1 +
 2 files changed, 23 insertions(+), 1 deletion(-)
 create mode 120000 CLAUDE.md

diff --git a/AGENTS.md b/AGENTS.md
index 80d1fac..870998a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -64,9 +64,10 @@ src/
     auth.rs            # AppState, KoboAuth extractor
     handlers.rs        # All Kobo API handlers
     models.rs          # Kobo JSON types (serde models)
-    resources.rs       # Kobo store resource dictionary
+    resources.rs       # Kobo store resource dictionary (131 entries; 4 overridden to point at us)
     router.rs          # Router construction
     sync.rs            # SyncEngine (incremental sync algorithm)
+    sync_point.rs      # Sync point tracking
     sync_token.rs      # Sync token encode/decode
 web/
   index.html           # Static HTML (embedded via include_str!)
@@ -225,6 +226,26 @@ error!("Failure: {e:?}");    // use Debug format for error-stack reports
 
 ### Important
 YOU MUST NEVER MODIFY THE API CONTRACT FOR THE KOBO API.
+This includes JSON shapes, header names (`x-kobo-synctoken`, `x-kobo-apitoken`,
+`x-kobo-sync`), route paths, and PascalCase field casing — all dictated by the
+Kobo device. Internal refactors are fine; wire-visible changes are not.
+
+### Architecture notes
+
+- **Two routers mounted:** Kobo API under `/kobo/{auth_token}`, web UI at root
+  (see `web.rs`; `web/index.html` is embedded via `include_str!`).
+- **Auth:** opaque token in URL path, validated by `KoboAuth` extractor against
+  the `auth_tokens` table. `/v1/auth/device` and `/v1/auth/refresh` are stubs
+  returning random tokens to satisfy the device — they do no real auth. Tokens
+  are provisioned via the web UI or by inserting a row directly.
+- **Calibre `metadata.db` is read-only.** All writes go to the app DB
+  (`kobors.db` by default). The two DBs have separate modules
+  (`db/calibre_db.rs` vs `db/app_db.rs`) — that separation is load-bearing.
+- **No migration framework** — schema lives as an inline SQL array in
+  `run_migrations()` in `db/app_db.rs`. Append new migrations; do not reorder.
+- **Resources dictionary** in `kobo/resources.rs` has 131 entries; only four
+  are rewritten (`image_host`, `image_url_template`,
+  `image_url_quality_template`, `library_sync`). Leave the rest alone.
 
 ### Conventions
 Prefer Iterators over loops
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 120000
index 0000000..47dc3e3
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file
-- 
2.51.2