gucmail 1.1.0__tar.gz

gucmail-1.1.0/.gitignore

@@ -0,0 +1,52 @@
+# Credentials and local overrides — never commit
+creds.env
+*.credentials.env
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+
+# Python / tooling
+__pycache__/
+*.py[cod]
+*.pyd
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+coverage.xml
+junit*.xml
+htmlcov/
+dist/
+build/
+.venv/
+venv/
+.tmp-*/
+
+# GUC Mail runtime/private state (may contain mailbox data)
+*.db
+*.db-shm
+*.db-wal
+*.sqlite
+*.sqlite3
+*.sqlite-wal
+*.sqlite-shm
+*.log
+.gucmail/
+gucmail-data/
+backups/
+downloads/
+recovery/
+diagnostic-bundles/
+gucmail-diagnostics*.json
+notifications*.ndjson
+gucmail-events*.ndjson
+
+# Editors and operating systems
+.idea/
+.vscode/
+.DS_Store
+Thumbs.db

gucmail-1.1.0/PKG-INFO

@@ -0,0 +1,227 @@
+Metadata-Version: 2.5
+Name: gucmail
+Version: 1.1.0
+Summary: An independent, security-focused terminal client for GUC Exchange mailboxes
+Author: GUC Mail CLI contributors
+License-Expression: MIT
+Keywords: email,ews,exchange,guc,terminal
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Communications :: Email :: Email Clients (MUA)
+Requires-Python: <3.15,>=3.11
+Requires-Dist: beautifulsoup4<5,>=4.12
+Requires-Dist: cryptography<51,>=43
+Requires-Dist: exchangelib==5.6.0
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: keyring<27,>=25
+Requires-Dist: lxml<7,>=5
+Requires-Dist: platformdirs<5,>=4.3
+Requires-Dist: pyfiglet<2,>=1.0.2
+Requires-Dist: python-dateutil<3,>=2.9
+Requires-Dist: rapidfuzz<4,>=3.10
+Requires-Dist: rich<15,>=13.9
+Requires-Dist: textual<8,>=7.5
+Requires-Dist: typer<1,>=0.15
+Provides-Extra: attachments
+Requires-Dist: openpyxl<4,>=3.1; extra == 'attachments'
+Requires-Dist: pypdf<7,>=6.16.1; extra == 'attachments'
+Requires-Dist: python-docx<2,>=1.1; extra == 'attachments'
+Requires-Dist: python-pptx<2,>=1.0; extra == 'attachments'
+Provides-Extra: desktop
+Requires-Dist: plyer<3,>=2.1; extra == 'desktop'
+Requires-Dist: windows-toasts==1.3.1; (sys_platform == 'win32') and extra == 'desktop'
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.2; extra == 'dev'
+Requires-Dist: hatchling<2,>=1.27; extra == 'dev'
+Requires-Dist: mypy<2,>=1.14; extra == 'dev'
+Requires-Dist: pytest-asyncio<2,>=0.25; extra == 'dev'
+Requires-Dist: pytest-cov<8,>=6; extra == 'dev'
+Requires-Dist: pytest<10,>=8.3; extra == 'dev'
+Requires-Dist: ruff<1,>=0.9; extra == 'dev'
+Requires-Dist: types-python-dateutil>=2.9; extra == 'dev'
+Provides-Extra: semantic
+Requires-Dist: numpy==2.3.5; extra == 'semantic'
+Description-Content-Type: text/markdown
+
+# gucmail
+
+Your GUC mailbox, in a terminal. Read, write, search, schedule and back up your mail without
+opening Outlook on the web. Calendar, contacts and tasks come along too. Everything works from
+the keyboard, and everything is scriptable.
+
+![The Mail workspace: folders, inbox and an open message](https://raw.githubusercontent.com/aynader/gucmail/main/docs/img/mail.png)
+
+It talks directly to the GUC Exchange server (EWS), so there's nothing to set up on the server
+and no third-party cloud in between. Your password stays in Windows Credential Manager, and
+your mail stays on your machine.
+
+*An independent project. Not affiliated with the German University in Cairo or Microsoft.*
+
+## Install
+
+You need Python 3.11 or newer.
+
+```powershell
+pip install "gucmail[desktop]"
+gucmail login          # asks for your GUC password, stores it in Windows Credential Manager
+gucmail tui            # opens the full-screen interface
+```
+
+Prefer an isolated install? `pipx install "gucmail[desktop]"`. Leave out `[desktop]` if you
+don't want Windows notifications.
+
+## Get around
+
+![Arrowing through the inbox and opening messages](https://raw.githubusercontent.com/aynader/gucmail/main/docs/img/mail-browse-demo.gif)
+
+Arrows move. **Enter** opens. **Tab** jumps between panes. **c** composes, **r** replies,
+**/** searches and **?** shows every shortcut. Mouse and scroll wheel work too.
+
+**Ctrl+K** opens the command palette. Type what you want in plain words:
+
+![Typing "schedule this for tomorrow 9am" into the palette](https://raw.githubusercontent.com/aynader/gucmail/main/docs/img/palette-demo.gif)
+
+It shows exactly what it understood (*Schedule current draft · tomorrow at 9:00*) and asks
+before it does anything. It never guesses at deleting.
+
+## Write
+
+![The composer with recipients and an attachment](https://raw.githubusercontent.com/aynader/gucmail/main/docs/img/compose.png)
+
+Reply, reply-all and forward. Cc and Bcc, attachments, signatures and importance. Recipients
+autocomplete from your contacts and recent mail. It warns you about an empty subject, a missing
+attachment you mentioned ("see attached…") or a typo in an address.
+
+Drafts save themselves, and if your laptop dies mid-sentence, the draft is waiting next time.
+**Undo Send** holds a message for a few seconds before it leaves.
+
+## Send later
+
+![The scheduled-mail queue](https://raw.githubusercontent.com/aynader/gucmail/main/docs/img/scheduled.png)
+
+```powershell
+gucmail send --to ta@example.edu --subject "Lab 6" --body-file report.txt --at "Monday 8:30"
+gucmail send --to me@example.edu --subject "Reminder" --body "Submit thesis" --in "2 hours"
+gucmail scheduled list
+```
+
+It always shows the exact time and time zone before queuing, refuses ambiguous dates like
+`03/04`, and never sends anything twice. It handles Cairo's daylight-saving switch. Messages
+go out from your PC, so it needs to be on. A Windows task can take care of that
+([how](https://github.com/aynader/gucmail/blob/main/docs/scheduling/windows-task-scheduler.md)).
+
+## Calendar, contacts, tasks
+
+![The calendar week view](https://raw.githubusercontent.com/aynader/gucmail/main/docs/img/calendar.png)
+
+Day, week, month and agenda views. Create events, accept or decline meetings, find a free
+slot, catch clashes, and import or export `.ics` files.
+
+| Contacts | Tasks |
+|---|---|
+| ![Contacts](https://raw.githubusercontent.com/aynader/gucmail/main/docs/img/contacts.png) | ![Tasks](https://raw.githubusercontent.com/aynader/gucmail/main/docs/img/tasks.png) |
+
+Contacts find duplicates and merge them, and import and export vCards. Tasks have due dates,
+progress and repeats.
+
+## Search
+
+```powershell
+gucmail search --sender "dr. mona" --after 2026-10-01 --has-attachments
+gucmail search "rubric" --all-folders
+gucmail index build --include-bodies             # build a local full-text index once…
+gucmail search --local --fuzzy "gradng rubrik"   # …then search it offline, typos and all
+```
+
+Saved searches, per-folder or whole-mailbox scope, and a search box in every view.
+
+## Notifications, even with the terminal closed
+
+```powershell
+gucmail notifications profiles create primary --name "Inbox" --enabled --activate
+gucmail startup enable --profile primary --apply     # a Windows task that starts at sign-in
+```
+
+A small background watcher checks your Inbox and shows a Windows toast for new mail. Clicking
+the toast opens the message. Quiet hours, rules ("only mail from @guc.edu.eg with
+'exam' in the subject") and signed webhooks are optional.
+[Details](https://github.com/aynader/gucmail/blob/main/docs/monitoring/headless-deployment.md).
+
+## Backups you can read without a connection
+
+![The Backup Center](https://raw.githubusercontent.com/aynader/gucmail/main/docs/img/backups.png)
+
+```powershell
+gucmail backup create --encrypt          # full backup, password-protected
+gucmail backup incremental               # just what changed since
+gucmail backup browse <id>               # read it offline, even with Wi-Fi off
+gucmail tui --offline                    # or browse cached mail in the interface
+```
+
+Backups never mark anything read and never change the server. Restores are planned first,
+with exact counts, and you confirm before anything is written.
+
+## Make it yours
+
+![The theme picker](https://raw.githubusercontent.com/aynader/gucmail/main/docs/img/themes.png)
+
+More than 600 themes with live preview, and your own colours or logo. Choose your columns,
+layouts and keyboard shortcuts in Settings, which you can search.
+
+![Settings](https://raw.githubusercontent.com/aynader/gucmail/main/docs/img/settings.png)
+
+## Scripts and automation
+
+Every command has `--json` (one envelope) or `--ndjson` (one record per line), stable exit
+codes, `--yes` for confirmations and `--dry-run` for anything that changes mail.
+
+```powershell
+gucmail --json messages list --folder inbox --limit 5
+gucmail --ndjson search --unread | ConvertFrom-Json | ? type -eq item | % { $_.data.subject }
+gucmail --yes messages move msg_12 msg_13 --to "Courses/Distributed Systems"
+gucmail quota                              # how full your mailbox is
+gucmail doctor                             # checks everything, offline unless you ask
+```
+
+There's more under `gucmail --help`: rules, automatic replies, insights ("who fills my
+mailbox?"), cleanup plans, clustering and an EWS capability browser.
+
+## Good to know
+
+- Some features depend on what GUC lets your account do: the directory, free/busy, rules,
+  delegates and quota limits. When the server says no, gucmail tells you so and never
+  invents a value.
+- It's tested on Windows 11. Linux and macOS should work but aren't tested yet.
+- More: [user guide](https://github.com/aynader/gucmail/blob/main/docs/user-guide/index.md) ·
+  [all commands](https://github.com/aynader/gucmail/blob/main/docs/command-reference/index.md) ·
+  [troubleshooting](https://github.com/aynader/gucmail/blob/main/docs/troubleshooting/index.md) ·
+  [privacy & security](https://github.com/aynader/gucmail/blob/main/docs/privacy-and-security/index.md) ·
+  [known limits](https://github.com/aynader/gucmail/blob/main/docs/STATUS.md)
+
+## Licence
+
+MIT License
+
+Copyright (c) 2026 gucmail contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software
+and associated documentation files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or
+substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
+BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

gucmail-1.1.0/README.md

@@ -0,0 +1,175 @@
+# gucmail
+
+Your GUC mailbox, in a terminal. Read, write, search, schedule and back up your mail without
+opening Outlook on the web. Calendar, contacts and tasks come along too. Everything works from
+the keyboard, and everything is scriptable.
+
+![The Mail workspace: folders, inbox and an open message](https://raw.githubusercontent.com/aynader/gucmail/main/docs/img/mail.png)
+
+It talks directly to the GUC Exchange server (EWS), so there's nothing to set up on the server
+and no third-party cloud in between. Your password stays in Windows Credential Manager, and
+your mail stays on your machine.
+
+*An independent project. Not affiliated with the German University in Cairo or Microsoft.*
+
+## Install
+
+You need Python 3.11 or newer.
+
+```powershell
+pip install "gucmail[desktop]"
+gucmail login          # asks for your GUC password, stores it in Windows Credential Manager
+gucmail tui            # opens the full-screen interface
+```
+
+Prefer an isolated install? `pipx install "gucmail[desktop]"`. Leave out `[desktop]` if you
+don't want Windows notifications.
+
+## Get around
+
+![Arrowing through the inbox and opening messages](https://raw.githubusercontent.com/aynader/gucmail/main/docs/img/mail-browse-demo.gif)
+
+Arrows move. **Enter** opens. **Tab** jumps between panes. **c** composes, **r** replies,
+**/** searches and **?** shows every shortcut. Mouse and scroll wheel work too.
+
+**Ctrl+K** opens the command palette. Type what you want in plain words:
+
+![Typing "schedule this for tomorrow 9am" into the palette](https://raw.githubusercontent.com/aynader/gucmail/main/docs/img/palette-demo.gif)
+
+It shows exactly what it understood (*Schedule current draft · tomorrow at 9:00*) and asks
+before it does anything. It never guesses at deleting.
+
+## Write
+
+![The composer with recipients and an attachment](https://raw.githubusercontent.com/aynader/gucmail/main/docs/img/compose.png)
+
+Reply, reply-all and forward. Cc and Bcc, attachments, signatures and importance. Recipients
+autocomplete from your contacts and recent mail. It warns you about an empty subject, a missing
+attachment you mentioned ("see attached…") or a typo in an address.
+
+Drafts save themselves, and if your laptop dies mid-sentence, the draft is waiting next time.
+**Undo Send** holds a message for a few seconds before it leaves.
+
+## Send later
+
+![The scheduled-mail queue](https://raw.githubusercontent.com/aynader/gucmail/main/docs/img/scheduled.png)
+
+```powershell
+gucmail send --to ta@example.edu --subject "Lab 6" --body-file report.txt --at "Monday 8:30"
+gucmail send --to me@example.edu --subject "Reminder" --body "Submit thesis" --in "2 hours"
+gucmail scheduled list
+```
+
+It always shows the exact time and time zone before queuing, refuses ambiguous dates like
+`03/04`, and never sends anything twice. It handles Cairo's daylight-saving switch. Messages
+go out from your PC, so it needs to be on. A Windows task can take care of that
+([how](https://github.com/aynader/gucmail/blob/main/docs/scheduling/windows-task-scheduler.md)).
+
+## Calendar, contacts, tasks
+
+![The calendar week view](https://raw.githubusercontent.com/aynader/gucmail/main/docs/img/calendar.png)
+
+Day, week, month and agenda views. Create events, accept or decline meetings, find a free
+slot, catch clashes, and import or export `.ics` files.
+
+| Contacts | Tasks |
+|---|---|
+| ![Contacts](https://raw.githubusercontent.com/aynader/gucmail/main/docs/img/contacts.png) | ![Tasks](https://raw.githubusercontent.com/aynader/gucmail/main/docs/img/tasks.png) |
+
+Contacts find duplicates and merge them, and import and export vCards. Tasks have due dates,
+progress and repeats.
+
+## Search
+
+```powershell
+gucmail search --sender "dr. mona" --after 2026-10-01 --has-attachments
+gucmail search "rubric" --all-folders
+gucmail index build --include-bodies             # build a local full-text index once…
+gucmail search --local --fuzzy "gradng rubrik"   # …then search it offline, typos and all
+```
+
+Saved searches, per-folder or whole-mailbox scope, and a search box in every view.
+
+## Notifications, even with the terminal closed
+
+```powershell
+gucmail notifications profiles create primary --name "Inbox" --enabled --activate
+gucmail startup enable --profile primary --apply     # a Windows task that starts at sign-in
+```
+
+A small background watcher checks your Inbox and shows a Windows toast for new mail. Clicking
+the toast opens the message. Quiet hours, rules ("only mail from @guc.edu.eg with
+'exam' in the subject") and signed webhooks are optional.
+[Details](https://github.com/aynader/gucmail/blob/main/docs/monitoring/headless-deployment.md).
+
+## Backups you can read without a connection
+
+![The Backup Center](https://raw.githubusercontent.com/aynader/gucmail/main/docs/img/backups.png)
+
+```powershell
+gucmail backup create --encrypt          # full backup, password-protected
+gucmail backup incremental               # just what changed since
+gucmail backup browse <id>               # read it offline, even with Wi-Fi off
+gucmail tui --offline                    # or browse cached mail in the interface
+```
+
+Backups never mark anything read and never change the server. Restores are planned first,
+with exact counts, and you confirm before anything is written.
+
+## Make it yours
+
+![The theme picker](https://raw.githubusercontent.com/aynader/gucmail/main/docs/img/themes.png)
+
+More than 600 themes with live preview, and your own colours or logo. Choose your columns,
+layouts and keyboard shortcuts in Settings, which you can search.
+
+![Settings](https://raw.githubusercontent.com/aynader/gucmail/main/docs/img/settings.png)
+
+## Scripts and automation
+
+Every command has `--json` (one envelope) or `--ndjson` (one record per line), stable exit
+codes, `--yes` for confirmations and `--dry-run` for anything that changes mail.
+
+```powershell
+gucmail --json messages list --folder inbox --limit 5
+gucmail --ndjson search --unread | ConvertFrom-Json | ? type -eq item | % { $_.data.subject }
+gucmail --yes messages move msg_12 msg_13 --to "Courses/Distributed Systems"
+gucmail quota                              # how full your mailbox is
+gucmail doctor                             # checks everything, offline unless you ask
+```
+
+There's more under `gucmail --help`: rules, automatic replies, insights ("who fills my
+mailbox?"), cleanup plans, clustering and an EWS capability browser.
+
+## Good to know
+
+- Some features depend on what GUC lets your account do: the directory, free/busy, rules,
+  delegates and quota limits. When the server says no, gucmail tells you so and never
+  invents a value.
+- It's tested on Windows 11. Linux and macOS should work but aren't tested yet.
+- More: [user guide](https://github.com/aynader/gucmail/blob/main/docs/user-guide/index.md) ·
+  [all commands](https://github.com/aynader/gucmail/blob/main/docs/command-reference/index.md) ·
+  [troubleshooting](https://github.com/aynader/gucmail/blob/main/docs/troubleshooting/index.md) ·
+  [privacy & security](https://github.com/aynader/gucmail/blob/main/docs/privacy-and-security/index.md) ·
+  [known limits](https://github.com/aynader/gucmail/blob/main/docs/STATUS.md)
+
+## Licence
+
+MIT License
+
+Copyright (c) 2026 gucmail contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software
+and associated documentation files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or
+substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
+BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

gucmail-1.1.0/docs/STATUS.md

@@ -0,0 +1,34 @@
+# Status and known limits
+
+GUCmail works for daily mail on Windows. Some areas have only been checked against a
+synthetic test mailbox, not the real GUC server. Please report problems along with
+the exact command and the message you saw. Never include your password.
+
+## What has been checked
+
+| Area | State |
+|---|---|
+| Install from wheel, `gucmail` and `python -m gucmail` launchers | Checked locally (Windows 11, Python 3.11) |
+| Mail: list, read, search, move, copy, delete, restore, flags, categories, export | Checked on a synthetic mailbox; core mail was also live-verified earlier |
+| Compose, reply, reply-all, forward, drafts, attachments | Checked on a synthetic mailbox; real sending is part of the live walkthrough |
+| Scheduled send, Undo Send, recurring messages, local scheduler | Checked with a synthetic backend; duplicate-send protection checked |
+| Calendar, contacts, tasks | Checked on a synthetic mailbox, including the Cairo daylight-saving change |
+| Backups (full, incremental, encrypted, verify, browse, restore plan) | Checked locally |
+| Local index, search, insights, cleanup previews | Checked on a synthetic mailbox |
+| Full-screen interface: every workspace, all palette routes, Settings, themes | Checked in Textual's built-in test mode at several sizes (not yet in a real Windows terminal) |
+
+## Known limits
+
+- **Server-dependent features.** These depend on what the GUC server and your account allow:
+  directory search, free/busy, inbox rules, automatic replies, delegates and quota thresholds.
+  If the server refuses one, GUCmail tells you so. It never shows made-up values.
+- **Scheduled sending is local.** It needs this computer and either `gucmail scheduled run`
+  or Windows Task Scheduler (see [Scheduling](scheduling/index.md)). If the computer is off,
+  messages are sent the next time the scheduler runs.
+- **Recurring messages** don't support end dates or specific-weekday rules yet.
+- **Startup speed.** Starting the full-screen interface can take 2–4 seconds on large mailboxes.
+- **Webhooks** accept only public HTTPS addresses, so local test servers are refused.
+- **Re-importing** the same `.ics` file creates duplicate events.
+- **Optional extras** (desktop notifications, attachment text extraction, semantic search,
+  Windows OCR) must be installed separately and have had limited testing.
+- **Platforms.** Linux and macOS should work but have not been tested yet.

gucmail-1.1.0/docs/advanced/index.md

@@ -0,0 +1,50 @@
+# Advanced workflows
+
+Advanced mode is a presentation choice; it does not expand Exchange permissions or change mailbox
+semantics.
+
+For every core TOML field, path override, type, default, and environment variable, use the
+[configuration reference](../configuration/index.md).
+
+## Search and analysis
+
+`gucmail search` performs a bounded server search. `gucmail index build` creates a disposable local
+FTS5 index; `index update`, `verify`, `optimize`, `rebuild`, and `clear` manage it. Fuzzy ranking and
+clustering are local and bounded. Optional semantic search uses the local `local-lsa-v1` model
+with TF-IDF and truncated SVD. Check `gucmail semantic status`, explicitly enable it, and review
+`semantic build` before applying a model build to an existing local index. It needs an available
+local NumPy runtime; it does not download a model or send mailbox text to a remote service.
+Use `semantic update` after index changes, and `semantic clear` or `disable` to remove the model
+or stop using it. Ordinary indexed text search remains available without semantic search.
+
+## Automation
+
+Use `gucmail --json` or `--ndjson`, stable exit codes, and `--non-interactive`. Scheduled sends live
+in the durable local state database. `gucmail scheduler run-once` is the supervisor-safe entry
+point. See [Scheduling](../scheduling/index.md) and [Monitoring](../monitoring/index.md).
+
+## EWS diagnostics
+
+Use `gucmail ews operations`, `describe`, `support-matrix`, and `diagnostics`. Registry status is
+static until a safe live probe occurs. `not_probed` does not mean supported or unsupported.
+Privileged and destructive operation families are registry-only unless a typed, safety-classified
+adapter exists.
+
+There is no arbitrary raw-SOAP execution command in this release. `ews request-preview` classifies
+an operation without constructing XML or sending a request. This is intentional: an unvalidated
+XML escape hatch would bypass typed serialization, request bounds, and mutation confirmation.
+The legacy raw-execution preference is shown as unavailable and cannot be enabled in Settings;
+Expert mode does not create an XML executor. The internal request loader rejects DTD declarations
+after parsing document metadata as well as checking bytes, including encoded UTF-16 input.
+
+## Local data boundaries
+
+Cache is disposable, the FTS index is rebuildable, scheduler/draft state is durable application
+state, and a backup is an independently verifiable archive. They are not interchangeable. See
+[Local data and retention](../privacy-and-security/local-data-locations-and-retention.md).
+
+## Mailbox delegates
+
+`gucmail ews delegates` reads the configured mailbox's delegate identities, six reported folder permission levels, meeting-copy preference and private-item access. In the TUI, use the Advanced palette command **Show Mailbox Delegates**. Refresh performs one read; Previous and Next navigate the loaded collection locally. No permissions are changed, and delegate creation, modification and deletion remain unavailable.
+
+EWS GetDelegate does not provide server pagination: `--limit` (default 100) and `--offset` slice one response locally, with a 1000-delegate safety cap. Missing permission fields are shown as **Not reported**, distinct from the explicit **None** permission level. This view does not enumerate every shared folder, effective access permission, Send As grant or delegated mailbox. Server version eligibility and this account's access remain unprobed; a permission error is not a claim that GUC never supports delegation.

gucmail-1.1.0/docs/api/index.md

@@ -0,0 +1,19 @@
+# Internal API guide
+
+The supported user API is the `gucmail` executable. Python modules are internal and may evolve, but
+the main extension boundaries are intentionally narrow:
+
+- mailbox gateway protocols in service modules;
+- `EWSGateway` for provider translation;
+- `BackupSource` and `RestoreTarget` for streamed backup/restore;
+- notification providers and webhook delivery abstractions;
+- domain dataclasses in `gucmail.models`;
+- the versioned `gucmail.output/v1` JSON envelope.
+
+Application services accept domain values and return immutable plans/results. A mutation should be
+split into `plan_*` and execution when users need to preview scope. Update plans must contain an
+explicit nonempty field list; unrestricted saves of partially fetched EWS objects are forbidden.
+
+The raw state database and backup object layout are not a general-purpose public API. Use service
+methods so migrations, locking, verification, redaction, and confirmation invariants remain intact.
+