Align internal documentation and maintained examples

docs/internal/storage.md

@@ -1,10 +1,16 @@
 # Internal: Storage
 
 ## Purpose
-Document remote object-store contracts and S3 implementation behavior.
+
+Explain the object-store interface and S3 implementation used by Narratio.
+Remote key layout and lifecycle belong in [Operations](../operations.md), while
+operator-selected storage fields and credential mechanisms belong in
+[Configuration](../config.md).
 
 ## Primary Contract
+
 `storage.ObjectStore` interface:
+
 - `List(ctx, prefix)`
 - `Download(ctx, key, localPath)`
 - `Upload(ctx, localPath, key, opts)`
@@ -14,15 +20,15 @@ Key invariant:
 - callers pass full bucket-relative keys;
 - storage implementations do not infer campaign/session/run prefixes.
 
-## Configuration
-`NewObjectStoreFromConfig` currently supports S3-backed stores from `pipeline.storage.*` config.
+## Composition
 
-S3 constructor behavior:
-- requires configured bucket;
-- uses region/endpoint/path-style options when set;
-- resolves credentials from configured env var names (with defaults).
+`NewObjectStoreFromConfig` constructs the S3-backed implementation from
+resolved configuration. The application loads configured filesystem secrets
+before calling it. The storage adapter consumes already-resolved values; it does
+not own discovery, defaults, or configuration validation.
 
 ## S3 Backend Behavior
+
 - normalizes object keys.
 - `List` paginates and returns normalized `ObjectInfo`.
 - `Download` writes local files with parent directory creation.
@@ -30,5 +36,13 @@ S3 constructor behavior:
 - `Exists` maps not-found responses to `false`.
 
 ## Invariants
+
 - storage layer is stateless regarding manifest/stage progression.
 - publish ordering semantics are owned by stage/app code, not storage adapters.
+
+## Implementation And Tests
+
+- Contract and S3 adapter: `internal/adapters/storage`
+- Composition: `internal/app/object_store.go`
+- Tests: `internal/adapters/storage/*_test.go`,
+  `internal/app/object_store_test.go`