intermittent commit

README.md

@@ -4,17 +4,48 @@
 **Repository type:** module (domain).
 <!-- govoplan-repository-type:end -->
 
-`govoplan-addresses` is the planned reusable address and recipient-source
-module. It should own long-lived address directories and make them available to
-campaigns, mail, forms, reporting, portal, and postbox modules through platform
+`govoplan-addresses` is the reusable address and recipient-source module. It
+owns long-lived address directories and makes them available to campaigns,
+mail, forms, reporting, portal, and postbox modules through platform
 capabilities.
 
 The campaign module may import campaign-local recipient tables, but reusable
 address management belongs here.
 
+## Current State
+
+Milestone 1 is implemented. The module now owns persistent local address books
+and contact CRUD under `/api/v1/addresses`, contributes `/address-book` to the
+WebUI, and registers address permissions, role templates, database migrations,
+tenant summaries, and uninstall guards.
+
+The first UI supports user, group, tenant, and system-scoped address books,
+multi-value contact methods, soft deletion, restore, read-only lookup/search,
+and vCard import/export for common contact fields. Imported vCards preserve
+source payload and revision metadata for later sync/conflict work.
+
+The backend and WebUI also support classical address lists: reusable groupings
+of contacts or specific contact methods within one address book. Campaigns can
+import address books and address lists through the core-mediated
+`addresses.recipient_source` capability without importing address-module
+internals. Broader operational `Verteiler` with mixed users, identities,
+groups, functions, raw recipients, and nested lists belong in
+`govoplan-dist-lists`.
+
+The backend now also contains connector-neutral sync infrastructure. Address
+books can be bound to external sources, sync attempts can record status,
+tokens, ETags, revisions, diagnostics, tombstones, and conflicts, and read-only
+or one-way-import sources make the owning address book read-only for normal
+write paths. CardDAV discovery, source binding, dry-run preview, inbound vCard
+sync, outbound create/update/delete for writable CardDAV sources, diagnostics,
+tombstones, conflict persistence, source disconnect/delete UX, and a first sync
+inspection UI are implemented. The conflict review UI compares stored local and
+remote field payloads, can apply a stored remote vCard payload, and supports
+manual per-field local/remote merge choices.
+
 ## Boundary
 
-`govoplan-addresses` should own:
+`govoplan-addresses` owns:
 
 - Adrema-style person, organization, household, and postal-address records
 - reusable email address lists and postal-letter recipient views
@@ -31,21 +62,46 @@ It must not own:
 - SMTP/IMAP transport
 - file storage
 - global identity authentication or RBAC evaluation
+- operational distribution lists/`Verteiler` with mixed recipient types
 
-## First Capability
+## First Capabilities
 
-The first useful contract should be a read-only recipient-source capability,
-for example `addresses.recipientSource`.
+The module exposes three core-mediated capabilities:
 
-It should let a consumer request a stable snapshot containing:
+- `addresses.lookup`: read-only contact/recipient lookup for autocomplete.
+- `addresses.recipient_source`: immutable recipient snapshots for campaign,
+  reporting, mail-build, forms, portal, and postbox workflows.
+- `addresses.contact_writer`: address-book-scoped write decisions and contact
+  creation for local or otherwise writable sources.
+
+`addresses.recipient_source` returns:
 
 - source id and display label
 - normalized recipient rows
-- email and postal address fields
-- legal-basis and consent metadata
+- email recipient fields
 - source update marker
 - provenance fields suitable for audit and campaign reports
 
+Recipient sources currently include complete address books and classical
+address lists. Address-list source IDs use `addresses:address_list:<id>` and
+preserve the address-list entry ID in recipient provenance. Address-list entries
+may point at a whole contact, a concrete email address, or a concrete postal
+address. Email-oriented consumers snapshot email targets and whole-contact
+entries with a usable email address; postal-only entries remain valid list
+members for later postal/document workflows.
+
 Consumers must store their own immutable snapshot when they need historical
 evidence. The addresses module remains the owner of the reusable source, not of
-the consumer's historical records.
+the consumer's historical records. Consumers must resolve these capabilities
+through the platform registry and must not import address ORM/service internals.
+
+`addresses.contact_writer` returns an explicit decision before a consumer shows
+or executes write actions: allowed/blocked, reason, user-facing message,
+required scopes, source kind, read-only state, and provenance. The decision is
+address-book specific; broader policy modules may later contribute to the same
+decision path, but consumers should not import or duplicate policy logic.
+
+## Design Documents
+
+- [Address module architecture](docs/ADDRESS_MODULE_ARCHITECTURE.md)
+- [Implementation plan](docs/IMPLEMENTATION_PLAN.md)