docs(config): specify autosave interaction contract

Author: Aaronontheweb

openspec/changes/netclaw-config-command/design.md

@@ -138,6 +138,29 @@ placeholder shell renders.
 Leaf editors get substantive round-trip and smoke coverage. Routed handoffs
 get shallow routing coverage only.
 
+### D11. Inline config editors autosave completed actions through one shared contract
+
+Inline config editors use a shared autosave interaction component instead of
+page-specific save buttons or one-off status text. The standard behavior is:
+
+- `Esc` backs out or cancels incomplete input; it never saves.
+- Completed actions save immediately after validation.
+- Text and multi-field input becomes a completed action only when accepted
+  with `Enter` / Apply.
+- Toggles, audience changes, enable/disable, add/remove, and confirmed reset
+  actions are completed actions.
+- Structural validation failures block writes and leave disk unchanged.
+- Runtime/probe failures may offer `Save anyway` only after the structurally
+  valid draft is known.
+- Each write is section-preserving and field-scoped to the editor's ownership
+  boundary.
+
+Alternative considered: explicit `[s] Save` staged editing. Rejected because
+the existing config surfaces behave like action editors, and mixing staged
+edits with navigation caused operators to lose unrelated channel configuration.
+The safer user model is “doing the thing saves the thing,” with `Esc` reserved
+for navigation/cancel.
+
 ## Risks / Trade-offs
 
 - The domain-oriented IA introduces more navigation depth.
@@ -151,6 +174,9 @@ get shallow routing coverage only.
 - Exposure-mode auto-pairing can fail on inconsistent state.
   Mitigation: fail loudly and route to doctor/docs/#875 rather than doing
   inline repair.
+- Autosave can surprise operators if every keypress writes.
+  Mitigation: only completed actions autosave; incomplete text entry remains
+  an in-memory draft until accepted with `Enter` / Apply.
 
 ## Migration Plan
 

openspec/changes/netclaw-config-command/proposal.md

@@ -81,14 +81,22 @@ Source PRDs: `PRD-004-cli-onboarding-and-config.md`,
   it edits before save, including local references and external probes when
   relevant. Structurally invalid config remains non-overridable; runtime or
   probe failures MAY offer `Save anyway`.
+- Inline leaf editors use one shared autosave interaction contract: completed
+  actions persist immediately after validation, `Esc` only navigates or
+  cancels incomplete input, and there is no explicit save key for ordinary
+  config edits.
+- Autosaves are atomic and section-preserving. An editor writes only the
+  fields it owns; disabling a provider or feature preserves dormant values,
+  while destructive removal requires an explicit reset/confirm action.
 - Round-trip preservation and test assertions are semantic, not
   byte-identical.
 - Leaf editors receive substantive round-trip and smoke coverage. Routed
   handoffs receive shallow routing coverage only.
 
 **In scope (MVP):** `netclaw config`, domain-oriented dashboard IA, routed
 handoffs for providers/models, leaf editors for the in-scope areas above,
-generalized validation behavior, exposure-mode dialogs within the existing
+generalized validation behavior, shared autosave interaction behavior,
+section-preserving persistence, exposure-mode dialogs within the existing
 config shape, missing-install refusal, and coverage aligned to leaf-vs-
 routed responsibilities.
 
@@ -124,6 +132,7 @@ sections.
 - Exposure-mode editing and validation.
 - Test surface for leaf editors, routing coverage, and generalized save
   validation.
+- Shared config TUI interaction component for autosaving completed actions.
 
 **Security and operational impact:**
 
@@ -135,3 +144,7 @@ sections.
 - Validation behavior is generalized beyond issue `#1151`; structural
   invalidity still blocks writes, while runtime reachability failures can
   be overridden with `Save anyway`.
+- Navigation no longer implies persistence. Completed config actions save
+  immediately, while `Esc` remains safe navigation/cancel behavior.
+- Section-preserving writes prevent one editor or provider action from
+  deleting unrelated persisted configuration.

openspec/changes/netclaw-config-command/specs/netclaw-config-command/spec.md

@@ -190,6 +190,83 @@ Runtime/probe failures MAY present `Save anyway`.
 - **THEN** the editor may show `Save anyway`
 - **AND** the operator can choose to persist the structurally valid config
 
+### Requirement: Inline config editors autosave completed actions consistently
+
+Every inline `netclaw config` leaf editor SHALL use a shared autosave
+interaction contract. The UI SHALL NOT require an explicit save key for
+ordinary config edits.
+
+Completed actions SHALL save immediately after validation. Completed actions
+include accepted text or multi-field forms, toggles, audience changes,
+enable/disable actions, add/remove actions, and confirmed reset actions.
+Incomplete text input SHALL remain an in-memory draft until accepted with
+`Enter` or an equivalent Apply action.
+
+`Esc` SHALL only navigate back or cancel incomplete input. It SHALL NOT save
+pending edits and SHALL NOT be required to complete a save.
+
+All autosaves SHALL be atomic: validation SHALL complete before files are
+written, and failed validation SHALL leave persisted config and secrets
+unchanged.
+
+#### Scenario: Completed toggle autosaves immediately
+
+- **GIVEN** an inline config leaf editor contains a boolean toggle
+- **WHEN** the operator toggles the setting
+- **THEN** the editor validates the resulting state
+- **AND** persists the change immediately when validation succeeds
+- **AND** shows a saved status without asking the operator to press a save key
+
+#### Scenario: Esc cancels draft text without persisting
+
+- **GIVEN** an inline config leaf editor contains a text field
+- **AND** the operator has typed a draft value but has not accepted it
+- **WHEN** the operator presses `Esc`
+- **THEN** the editor navigates back or cancels the draft
+- **AND** the persisted config is unchanged
+
+#### Scenario: Invalid completed action writes nothing
+
+- **GIVEN** an inline config leaf editor contains a structurally invalid draft
+- **WHEN** the operator accepts the action
+- **THEN** validation fails
+- **AND** no config or secrets file is modified
+- **AND** the UI shows the validation error
+
+### Requirement: Inline config persistence is section-preserving
+
+Inline config leaf editors SHALL persist only the sections, providers,
+fields, and sidecar files they own. Saving one provider or sub-area SHALL NOT
+delete or reset unrelated providers, inactive values, secrets, audiences, or
+sidecar files.
+
+Disable actions SHALL preserve dormant configuration and secrets while writing
+only the runtime-enabled flag. Destructive removal SHALL require an explicit
+reset/confirm action and SHALL be scoped to the confirmed target.
+
+#### Scenario: Disabling one channel provider preserves its dormant setup
+
+- **GIVEN** Slack has saved channels, audiences, allowed users, and secrets
+- **WHEN** the operator disables Slack from the Channels config area
+- **THEN** Slack `Enabled` is persisted as `false`
+- **AND** Slack channels, audiences, allowed users, and secrets remain
+  persisted
+
+#### Scenario: Saving one channel provider does not wipe another provider
+
+- **GIVEN** Slack and Discord both have saved channel configuration
+- **WHEN** the operator adds a Discord channel and the action autosaves
+- **THEN** the Discord addition is persisted
+- **AND** the saved Slack configuration remains present and unchanged except
+  for any explicit Slack action the operator completed
+
+#### Scenario: Reset is the only provider-destructive action
+
+- **GIVEN** a provider has saved channel configuration and secrets
+- **WHEN** the operator confirms reset for that provider
+- **THEN** only that provider's config and secrets are removed
+- **AND** other providers remain unchanged
+
 ### Requirement: Coverage follows leaf ownership
 
 Leaf editors SHALL receive substantive round-trip and smoke coverage.

openspec/changes/netclaw-config-command/tasks.md

@@ -116,11 +116,32 @@
 
 ## 14. Coverage
 
-- [ ] 14.1 Add substantive round-trip tests for leaf editors.
-- [ ] 14.2 Add substantive smoke tapes for leaf editors.
-- [ ] 14.3 Use semantic preservation assertions, not byte-identical file
+- [ ] 14.1 Add shared autosave contract tests for every inline config leaf:
+  completed actions persist, `Esc` does not save incomplete drafts, and
+  invalid completed actions write nothing.
+- [ ] 14.2 Add substantive round-trip tests for leaf editors.
+- [ ] 14.3 Add substantive smoke tapes for leaf editors.
+- [ ] 14.4 Use semantic preservation assertions, not byte-identical file
   assertions.
-- [ ] 14.4 Add shallow routing coverage for routed handoffs only.
+- [ ] 14.5 Add shallow routing coverage for routed handoffs only.
+
+## 16. Shared autosave config interaction
+
+- [ ] 16.1 Introduce a shared autosave interaction component/contract for
+  inline config editors.
+- [ ] 16.2 Remove explicit save-key behavior and copy from inline config
+  editors; completed actions autosave instead.
+- [ ] 16.3 Ensure `Esc` only navigates/cancels and never persists edits.
+- [ ] 16.4 Ensure each autosave validates before writing and leaves files
+  unchanged on validation failure.
+- [ ] 16.5 Ensure writes are section-preserving and field-scoped to editor
+  ownership boundaries.
+- [ ] 16.6 Harden Channels persistence so provider enable/disable, add/remove,
+  audience, allowed-user, direct-message, and credential actions autosave
+  provider-granular changes without wiping unrelated providers.
+- [ ] 16.7 Add the regression: seed Slack and Discord, add a Discord channel,
+  disable Slack, press `Esc`, and verify only completed autosaves occurred
+  with Slack dormant setup preserved.
 
 ## 15. Quality gates