Normalize internal component documentation

docs/internal/notify.md

@@ -1,35 +1,48 @@
-# Notify
+# Notification Internals
+
+Audience: developers and LLM coding agents changing `internal/notify` or app notification wiring.
 
 ## Purpose
 
-`internal/notify` defines the internal notification interface used by the application runner.
+`internal/notify` defines the notification interface used by app orchestration after successful destination publication or replacement.
 
-## Inputs and outputs
+## Inputs And Outputs
 
-Input is a notification event containing pipeline id, destination id, bundle id, bundle path, action, and output metadata. The interface returns an error so app orchestration can treat notification failures as destination failures.
-
-## Current behavior
-
-The implemented notifier is a no-op. It is invoked only after a successful publish or replacement. Dry-run, skipped destinations, and failed destinations do not invoke it.
-
-## Failure behavior
-
-`notify.Noop` always succeeds unless the context is already canceled. If a configured notifier returns an error, `internal/app` records that destination as failed and continues with remaining destinations.
+Input is a context and notification event containing pipeline id, destination id, bundle id, bundle path, action, and output metadata. Output is an error that app orchestration can record as a destination-scoped failure.
 
 ## Boundaries
 
-External notification adapters and user-facing notification configuration are outside current behavior.
+Only the no-op notifier exists in the repository. The package does not load config, send network requests, write destination state, publish files, or own run reporting.
 
-## Tests
+## Config Fields Used
 
-Before changing notification behavior, inspect:
+None.
+
+## Adapters Used
+
+None.
+
+## State And Manifest Behavior
+
+Notification events carry output metadata projected from publish plans. The package does not inspect source manifests or destination state.
+
+## Skip And Resume Behavior
+
+Dry-run, skipped destinations, failed destinations, and planning failures do not notify. The no-op notifier has no durable state.
+
+## Failure Behavior
+
+`notify.Noop` returns the context error when the context is canceled; otherwise it succeeds. If another notifier implementation returns an error, `internal/app` records the affected destination as failed and continues with remaining destinations where applicable.
+
+## Tests To Inspect
 
 - `internal/notify`
-- `internal/app/run_test.go`
+- `internal/app/run_notify.go`
+- notification coverage in `internal/app/run_test.go`
 
-## Invariants
+## Architectural Invariants
 
-- Notifications are emitted only after successful publish or replacement execution.
+- Notifications occur only after successful publish or replacement execution.
 - Dry-run never notifies.
 - Skipped and failed destinations never notify.
 - The default app notifier is `notify.Noop`.