dazzer-connect 0.1.1 → 0.3.0

package/README.md

@@ -67,21 +67,77 @@ The second carries a pass, for clients that cannot do that:
 
 Merge either one with any `mcpServers` entries you already have, save, and restart your client.
 
+## Put files into Dazzer
+
+```bash
+dazzer add report.pdf
+dazzer add ./backlog
+```
+
+A folder is walked with its subfolders. Hidden files are left alone, and nothing outside the folder is ever sent. The first time, you are asked which space things go in: run the same command again with `--space "<name>"`, or with `--keep-to-myself`. A folder run ends with a count of what went in and what was skipped. Add `--why` to see each file that was skipped, and why.
+
+### With what your assistant wrote about each file
+
+Your own AI assistant can read the files and say what each one is. It writes that into one JSON file, called the descriptions file. Each key is a file's path inside the folder, or the file's name when you add just one, and what sits under a key is that file's entry:
+
+```json
+{
+  "notes/plan.md": {
+    "description": {
+      "what_it_is": { "text": "the plan for the spring launch", "quote": "Spring launch plan" },
+      "what_it_covers": { "text": "who ships what, week by week", "quote": "Week 1: design review" },
+      "what_it_decides": null,
+      "how_much_was_read": { "all": true }
+    },
+    "facts": [{ "text": "the launch is on 14 April", "quote": "Launch: 14 April" }],
+    "document_date": "2026-03-01"
+  },
+  "scan.png": {
+    "description": {
+      "what_it_is": { "text": "a photo of the gate log", "quote": "GATE LOG" },
+      "what_it_covers": { "text": "who signed for the gate overnight", "quote": "night porter" },
+      "what_it_decides": null,
+      "how_much_was_read": { "all": true }
+    },
+    "transcription": "GATE LOG\nSigned by the night porter at four."
+  }
+}
+```
+
+Save it beside the folder, never inside it — for example as `backlog-descriptions.json` next to `backlog`. Inside the folder, a later `dazzer add ./backlog` without `--described-in` would send it like any other file. Then:
+
+```bash
+dazzer add ./backlog --described-in ./backlog-descriptions.json
+```
+
+Each file goes with its own entry. The descriptions file named by `--described-in` is not sent with them, even when it sits inside the folder, and the run says to move it.
+
+- Each entry's form is checked before its file is sent. An entry in a form Dazzer refuses, such as a date written as "March 2026", holds its file back, and a line names the field and the form it takes. What the entry says is judged by Dazzer once the file has arrived.
+- A file with no entry goes in as usual, and the count names it.
+- An entry that names no file being added is reported, and nothing is sent for it. If no entry names a file being added, nothing is sent at all.
+- A file Dazzer refuses although it had an entry is named, in Dazzer's own words.
+- Whatever Dazzer did not keep of an entry is printed file by file, with what to change.
+- Sent again, a folder already in Dazzer says how many files took the description sent now, how many already had one, and how many did not take the one sent.
+
+An assistant that can run commands runs this one itself. One that cannot gives you the descriptions file to save beside the folder, and the line to run.
+
 ## Other commands
 
 ```bash
 dazzer auth status    # is my sign-in still good?
-dazzer auth logout    # sign out and delete what is stored
+dazzer auth logout    # cancel your sign-in and remove it from this machine
 dazzer --help
 ```
 
 `auth status` asks the server rather than trusting what is on disk, so it can tell you your sign-in has been revoked elsewhere.
 
+`auth logout` cancels your sign-in at the server and removes it from this machine, and says "Signed out." only when it knows both happened. If your sign-in could not be cancelled right now — the server did not answer, or your credential store would not open or would not let it go — it says so, fails, and keeps it, so running it again can finish. If the server gives an answer that will not change, it removes the sign-in from this machine and tells you it stops working once it goes 30 days unused. A pass you pasted into another app keeps working until it expires, within the hour.
+
 ## Where your sign-in is kept
 
 Your passes go in your operating system's own credential store — Keychain on macOS, Credential Manager on Windows, Secret Service on Linux. Nothing is written in plain text. The rest, such as which server you signed in to and when it expires, sits in a settings folder alongside your other applications' settings.
 
-Plenty of servers and containers have no credential store at all. Sign-in still completes and prints the blocks above, and `auth status` tells you that is what happened rather than claiming you are signed out.
+Plenty of servers and containers have no credential store at all. Sign-in still completes and prints the blocks above, and `auth status` tells you that is what happened rather than claiming you are signed out. On such a machine `auth logout` cannot check for a saved sign-in, so it will not call itself a sign-out; on Linux, `dazzer auth logout --forget-this-machine` removes this machine's record instead, says that nothing was cancelled, and leaves any sign-in still in the credential store where it is. It refuses on macOS and Windows, whose credential store is locked rather than missing, and when sign-in recorded saving a sign-in here.
 
 ## Settings
 
@@ -92,6 +148,9 @@ Everything points at production unless you say otherwise.
 | `DAZZER_AUTH_ISSUER` | where you sign in | `https://auth.dazzer.io` |
 | `DAZZER_AUTH_CLIENT_ID` | which client is asking | `dazzer-cli-local` |
 | `DAZZER_AUTH_RESOURCE` | what you are signing in to | `https://graph.dazzer.io/mcp` |
+| `DAZZER_API_BASE_URL` | where Dazzer itself is | `https://graph.dazzer.io` |
+
+The first three are about signing in. The last one is Dazzer itself — the same service, seen from the other side — and it is the address the tool sends to once it has a sign-in to carry. Both addresses have to be `https`; an unencrypted one is refused before anything is sent.
 
 Signing in and checking status each take a matching flag — `--issuer`, `--client-id`, `--resource` — which wins over the setting. Against a sign-in server running on your own machine: