docs: require acknowledged settings completion

docs/internals/consistency-settings-completion.md

@@ -0,0 +1,38 @@
+# Settings completion follows persistence
+
+Proposed contract, not a ratified maintainer decision: a settings form that says
+“Added” or “Saved”, or closes to signal a successful save, must first receive
+confirmation from the store that owns the setting. Accepting input or scheduling
+an update is not that confirmation.
+
+[Apple's Feedback guidance](https://developer.apple.com/design/human-interface-guidelines/feedback)
+and [Loading guidance](https://developer.apple.com/design/human-interface-guidelines/loading)
+support keeping people informed while work proceeds. Here, that means a pending
+save prevents duplicate submission; a failed or interrupted save keeps the draft
+and provides a retry path. Only confirmed success may clear the form or announce
+completion.
+
+This boundary spans the form, client command, and authoritative persistence.
+A promise, including `Promise<void>`, confirms persistence only if it resolves
+after the write succeeds and rejects on failure. Scheduling a write or swallowing
+its error does not provide confirmation. Server-owned
+settings require the command's successful receipt for the environment selected at
+submission. Closing, reopening, or changing environments must detach the old
+completion from the new form; it does not cancel or undo a server write.
+
+The rule applies to explicit settings completion claims in web, Electron, and
+React Native where those forms exist. The additional-provider form and custom-model editors are shared by
+web and Electron. Custom-model add and edit retain their drafts until the
+environment confirms persistence; removal cleans up local preferences only
+after that confirmation. Quiet preference controls may update optimistically only
+if their callers observe write failures, show an error and reconcile the displayed
+value with persisted state. Otherwise they must await persistence. A helper that
+logs a failed write and resolves does not qualify for this exception. This contract does
+not require modal saves for toggles, change shared-setting synchronization, or
+extend to clipboard acknowledgements.
+
+Observable acceptance cases are delayed success with pending feedback and one
+submission; rejection or interruption with retained input and an actionable
+error; successful retry; and an old receipt arriving after a form or environment
+change without dismissing the current form or announcing its success. A server
+receipt confirms persistence, not provider authentication or readiness.