From 4dc7d225d56fa795042249f9f6a6e59e50a730a6 Mon Sep 17 00:00:00 2001
From: wagesj45 <jordan@jordanwages.com>
Date: Sun, 19 Apr 2026 01:58:59 -0500
Subject: [PATCH] Add repository agent instructions

---
 AGENTS.md | 93 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 93 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..e6ac055
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,93 @@
+# AGENTS.md
+
+## Purpose
+
+This repository is a Thunderbird Manifest V3 Filelink/cloudFile provider scaffold for PsiTransfer. Treat it as an integration-in-progress, not a finished provider.
+
+## Required source of truth
+
+Before changing PsiTransfer integration behavior:
+
+1. Check whether `/tmp/psitransfer` already exists.
+2. If it does not exist, clone it:
+
+```bash
+git clone https://github.com/psi-4ward/psitransfer.git /tmp/psitransfer
+```
+
+3. Use `/tmp/psitransfer` as the primary source of truth for the effective upload/download interface.
+4. Use the official Thunderbird docs, especially:
+   https://webextension-api.thunderbird.net/en/mv3/cloudFile.html
+
+## Thunderbird library rule
+
+Thunderbird add-ons are strict about how third-party libraries are referenced. Do not load `tus-js-client` or other dependencies from a CDN at runtime.
+
+For this repository:
+
+- Use the vendored local copy at `vendor/tus.js`
+- Do not switch background/UI code to `https://cdn.jsdelivr.net/...` references
+- If the tus client needs to be updated, download the new bundle into the repository first and record the exact resolved version in docs or commit notes
+
+Current vendored tus client:
+
+- Source URL used: `https://cdn.jsdelivr.net/npm/tus-js-client@latest/dist/tus.js`
+- Resolved package version at download time: `4.3.1`
+- Local path: `vendor/tus.js`
+
+## Interpretation rules
+
+Distinguish clearly between:
+
+- `tus` standard behavior
+- PsiTransfer-specific behavior
+- Thunderbird `cloudFile` / Filelink behavior
+
+Do not invent a polished public PsiTransfer API if the code only exposes an internal frontend-facing interface.
+
+When uncertain, cite exact PsiTransfer source files and line ranges in notes or docs. Prefer adding a TODO with file references over guessing behavior.
+
+## Minimal-v1 scope
+
+Preserve a minimal-v1 mindset:
+
+- configure endpoint
+- upload
+- obtain share URL
+- skip delete/rename/reuse if source support is weak
+
+Prefer explicit TODOs over guessed implementations.
+
+## Concrete workflow
+
+1. Inspect `manifest.json` and the existing scaffold under `src/` and `ui/`.
+2. Inspect `/tmp/psitransfer` frontend and backend routes.
+3. Document the inferred HTTP flow with exact source references.
+4. Implement the minimal upload path.
+5. Verify the generated share URL and Thunderbird `cloudFile` return shape.
+6. Only then add optional delete, reuse, or rename support.
+
+## PsiTransfer-specific notes to verify
+
+- Upload config is exposed from PsiTransfer server-side code, not an external API contract by itself.
+- Upload password behavior and bucket password behavior are different concerns.
+- `sid` handling may mix PsiTransfer frontend convenience with server upload metadata requirements.
+- Bucket locking is part of the upload flow and must not be dropped casually.
+- Delete and rename support must not be claimed unless the PsiTransfer source clearly supports them for uploaded items.
+
+## Files to update carefully
+
+- `src/psitransfer/client.js`
+- `src/cloudfile/provider.js`
+- `src/cloudfile/account-store.js`
+- `docs/psitransfer-notes.md`
+- `README.md`
+
+## Documentation expectation
+
+If you infer or change transport behavior, update `docs/psitransfer-notes.md` with:
+
+- the exact PsiTransfer files consulted
+- the relevant line ranges
+- what is confirmed
+- what is still unresolved