General copy edits

Author: crandmck

docs/context-settings.md

@@ -92,7 +92,7 @@ with open("config/settings.json", "r") as f:
 ctx = Context(settings)
 ```
 
-## Class diagram 
+## Class diagram
 
 ```mermaid
 classDiagram
@@ -222,7 +222,7 @@ ctx = Context.from_dict({
     }
 })
 
-builder = Builder(manifest_json, ctx)
+builder = Builder(manifest_json, context=ctx)
 
 with open("source.jpg", "rb") as src, open("output.jpg", "w+b") as dst:
     builder.sign(signer, "image/jpeg", src, dst)
@@ -246,7 +246,7 @@ ctx = Context.from_dict({
 })
 
 with open("manifest.c2pa", "rb") as archive:
-    builder = Builder({}, ctx)
+    builder = Builder({}, context=ctx)
     builder.with_archive(archive)
     # builder now has the archived definition + context settings
 ```
@@ -644,7 +644,7 @@ ctx = Context.from_dict({
     }
 })
 
-builder = Builder(manifest_json, ctx)
+builder = Builder(manifest_json, context=ctx)
 with open("source.jpg", "rb") as src, open("output.jpg", "w+b") as dst:
     builder.sign("image/jpeg", src, dst)
 ```
@@ -664,7 +664,7 @@ signer = Signer.from_info(signer_info)
 ctx = Context(settings, signer)
 # signer is now invalid and must not be used directly again
 
-builder = Builder(manifest_json, ctx)
+builder = Builder(manifest_json, context=ctx)
 with open("source.jpg", "rb") as src, open("output.jpg", "w+b") as dst:
     builder.sign("image/jpeg", src, dst)
 ```
@@ -675,7 +675,7 @@ For full programmatic control, pass a `Signer` directly to `Builder.sign()`:
 
 ```py
 signer = Signer.from_info(signer_info)
-builder = Builder(manifest_json, ctx)
+builder = Builder(manifest_json, context=ctx)
 
 with open("source.jpg", "rb") as src, open("output.jpg", "w+b") as dst:
     builder.sign(signer, "image/jpeg", src, dst)

docs/intents.md

@@ -1,6 +1,6 @@
 # Using Builder intents
 
-_Intents_ enable validation, add required actions that are required by the C2PA specification, and help prevent invalid operations when using a `Builder`. Intents are about the operation (create, edit, update) executed on the source asset.
+_Intents_ enable validation, add the actions required by the C2PA specification, and help prevent invalid operations when using a `Builder`. Intents are about the operation (create, edit, update) executed on the source asset.
 
 ## Why use intents?
 
@@ -125,7 +125,7 @@ flowchart TD
 
 ## How intents relate to the source stream
 
-The intent operates on the source passed to `sign()`, not on any ingredient added via `add_ingredient`.
+The intent operates on the source passed to `sign()`, not on any ingredient added via `add_ingredient()`.
 
 The following diagram shows what happens at sign time for each intent:
 
@@ -168,7 +168,7 @@ For `Edit` and `Update` intents, `Builder` looks at the source stream, and if no
 
 ### How intent relates to `add_ingredient`
 
-The `Builder` intent controls what the Builder does with the source stream (source asset) at sign time. The `add_ingredient` method adds other ingredients explicitly. These are separate concerns.
+The `Builder` intent controls what the `Builder` does with the source stream (source asset) at sign time. The `add_ingredient` method adds other ingredients explicitly. These are separate concerns.
 
 ```mermaid
 flowchart TD

docs/selective-manifests.md

@@ -34,7 +34,7 @@ The fundamental workflow is:
 
 ## Reading an existing manifest
 
-Use `Reader` with a `Context` to extract the manifest store JSON and any binary resources (thumbnails, manifest data). The source asset is never modified. The context is used for trust configuration (which certificates are trusted when validating signatures) and verification settings. See [Configuring Reader](../context.md#configuring-reader) and [Trust configuration](../context.md#trust-configuration) for details.
+Use `Reader` with a `Context` to extract the manifest store JSON and any binary resources (thumbnails, manifest data). The source asset is never modified. The context is used for trust configuration (which certificates are trusted when validating signatures) and verification settings. See [Configuring `Reader`](context-settings.md#with-reader) and [Trust configuration](context-settings.md#trust) for details.
 
 ```py
 ctx = Context.from_dict({
@@ -70,7 +70,7 @@ with open("thumbnail.jpg", "wb") as f:
 ## Filtering into a new Builder
 
 > [!NOTE]
-> All examples on this page use `Context` with `Reader` and `Builder`. For `Reader`, the context provides trust configuration and verification settings: `Reader(format, source, context=ctx)`. For `Builder`, the context provides custom settings (thumbnails, claim generator, intent): `Builder(manifest_json, context=ctx)`. When a signer is configured in the context, `builder.sign()` is called without a signer instance. See [Context](../context.md) for details.
+> All examples on this page use `Context` with `Reader` and `Builder`. For `Reader`, the context provides trust configuration and verification settings: `Reader(format, source, context=ctx)`. For `Builder`, the context provides custom settings (thumbnails, claim generator, intent): `Builder(manifest_json, context=ctx)`. When a signer is configured in the context, `builder.sign()` is called without a signer instance. See [Context and settings](context-settings.md) for details.
 
 Each example below creates a **new `Builder`** from filtered data. The original asset and its manifest store are never modified.
 
@@ -482,7 +482,7 @@ with open("signed_asset.jpg", "rb") as signed:
 
 ## Working with archives
 
-A `Builder` represents a **working store**: a manifest that is being assembled but has not yet been signed. Archives serialize this working store (definition + resources) to a `.c2pa` binary format, allowing to save, transfer, or resume the work later. For more background on working stores and archives, see [Working stores](https://opensource.contentauthenticity.org/docs/rust-sdk/docs/working-stores).
+A `Builder` represents a **working store**: a manifest that is being assembled but has not yet been signed. Archives serialize this working store (definition + resources) to a `.c2pa` binary format, allowing to save, transfer, or resume the work later. For more background on working stores and archives, see [Working stores and archives](working-stores.md).
 
 There are two distinct types of archives, sharing the same binary format but being conceptually different: builder archives (working store archives) and ingredient archives.
 
@@ -632,7 +632,8 @@ layer_actions = [
 ]
 ```
 
-> **Naming convention:** Vendor parameters must use reverse domain notation with period-separated components (e.g., `com.mycompany.tool`, `net.example.session_id`). Some namespaces (e.g., `c2pa` or `cawg`) may be reserved.
+> [!NOTE]
+> Vendor parameters must use reverse domain notation with period-separated components (for example, `com.mycompany.tool`, `net.example.session_id`). Some namespaces (for example, `c2pa` or `cawg`) may be reserved.
 
 ### Extracting ingredients from a working store
 
@@ -692,7 +693,7 @@ with Builder({
 ```
 
 > [!NOTE]
-> When restoring from an archive, `with_archive()` preserves context settings while `from_archive()` does not. See [Working with archives](../working-stores.md#working-with-archives) for the full comparison.
+> When restoring from an archive, `with_archive()` preserves context settings while `from_archive()` does not. See [Working with archives](working-stores.md#working-with-archives) for the full comparison.
 
 **Step 2:** Read the archive and extract ingredients:
 
@@ -733,7 +734,7 @@ with Reader("application/c2pa", archive_stream, context=ctx) as reader:
 ### Merging multiple working stores
 
 > [!NOTE]
-> The `Builder` construction and signing in the merge workflow also support `Context`. The caller can pass `context=ctx` to `Builder()` and call `sign()` without a signer argument when the context has one. See [Context](../context.md) for details.
+> The `Builder` construction and signing in the merge workflow also support `Context`. The caller can pass `context=ctx` to `Builder()` and call `sign()` without a signer argument when the context has one. See [Context and settings](context-settings.md) for details.
 
 In some cases it is necessary to merge ingredients from multiple working stores (builder archives) into a single `Builder`. This should be a **fallback strategy**. The recommended practice is to maintain a single active working store and add ingredients incrementally (archived ingredient catalogs help with this). Merging is available when multiple working stores must be consolidated.
 

docs/usage.md

@@ -154,12 +154,12 @@ Use the `Reader` to read C2PA data from the specified asset file.
 
 This examines the specified media file for C2PA data and generates a report of any data it finds. If there are validation errors, the report includes a `validation_status` field.
 
-An asset file may contain many manifests in a manifest store. The most recent manifest is identified by the value of the `active_manifest` field in the manifests map. The manifests may contain binary resources such as thumbnails which can be retrieved with `resource_to_stream` using the associated `identifier` field values and a `uri`.
+An asset file may contain many manifests in a manifest store. The most recent manifest is identified by the value of the `active_manifest` field in the manifests map. The manifests may contain binary resources such as thumbnails which can be retrieved with `resource_to_stream()` using the associated `identifier` field value as the URI.
 
 > [!NOTE]
 > For a comprehensive reference to the JSON manifest structure, see the [Manifest store reference](https://opensource.contentauthenticity.org/docs/manifest/manifest-ref).
 
-Pass a `Context` to apply custom settings to the Reader, such as trust anchors or verification flags.
+Pass a `Context` to apply custom settings to the `Reader`, such as trust anchors or verification flags.
 
 ```py
 try:
@@ -181,7 +181,7 @@ except Exception as err:
 > [!WARNING]
 > This example accesses the private key and security certificate directly from the local file system.  This is fine during development, but doing so in production is insecure. Instead use a Key Management Service (KMS) or a hardware security module (HSM) to access the certificate and key; for example as show in the [C2PA Python Example](https://github.com/contentauth/c2pa-python-example).
 
-Pass a `Context` to the Builder to apply custom settings during signing. The signer is still passed explicitly to `builder.sign()`.
+Pass a `Context` to the `Builder` to apply custom settings during signing. The signer is still passed explicitly to `builder.sign()`.
 
 ```py
 try:

docs/working-stores.md

@@ -45,7 +45,7 @@ For more information, see:
 
 - [Reading manifest stores from assets](#reading-manifest-stores-from-assets)
 - [Creating and signing manifests](#creating-and-signing-manifests)
-- [Embedded vs external manifests](#embedded-vs-external-manifests)
+- [Embedded versus external manifests](#embedded-versus-external-manifests)
 
 ### Working store
 
@@ -59,7 +59,7 @@ A _working store_ is a `Builder` object representing an editable, in-progress ma
 
 **Example:** When you create a `Builder` object and add assertions to it, you're dealing with a working store, as it is an "in progress" manifest being built.
 
-For more information, see [Using Working stores](#using-working-stores).
+For more information, see [Using working stores](#using-working-stores).
 
 ### Archive
 
@@ -68,7 +68,7 @@ A _C2PA archive_ (or just _archive_) contains the serialized bytes of a working
 **Characteristics:**
 
 - Portable serialization of a working store (`Builder`).
-- Save an archive by using `Builder.to_archive()` and restore a full working store from an archive by using `Builder.with_archive()` (with a Builder created from a Context).
+- Save an archive by using `Builder.to_archive()` and restore a full working store from an archive by using `Builder.with_archive()` (with a `Builder` created from a `Context`).
 - Useful for separating manifest preparation ("work in progress") from final signing.
 
 For more information, see [Working with archives](#working-with-archives).
@@ -99,7 +99,7 @@ with open("signed_image.jpg", "rb") as stream:
     manifest_json = reader.json()
 ```
 
-For full details on `Context` and `Settings`, see [Using Context to configure the SDK](../context.md).
+For full details on `Context` and `Settings`, see [Context and settings](context-settings.md).
 
 ### Understanding Reader output
 
@@ -242,17 +242,6 @@ manifest_store_json = reader.json()
 
 ## Creating and signing manifests
 
-### Creating a Builder (working store)
-
-```py
-ctx = Context.from_dict({
-    "builder": {
-        "thumbnail": {"enabled": True}
-    }
-})
-builder = Builder(manifest_json, context=ctx)
-```
-
 ### Creating a Signer
 
 For testing, create a `Signer` with certificates and private key:
@@ -417,10 +406,11 @@ with open("source.jpg", "rb") as src, open("signed.jpg", "w+b") as dst:
 
 ## Working with ingredients
 
-Ingredients represent source materials used to create an asset, preserving the provenance chain. Adding an ingredient to a manifest creates a verifiable link from the current asset back to its source material. 
-The `relationship` field describes how the source (ingredient) was used: `"parentOf"` for a direct edit, `"componentOf"` for an element composited into a larger work, or `"inputTo"` for a general input. 
+Ingredients represent source materials used to create an asset, preserving the provenance chain. Adding an ingredient to a manifest creates a verifiable link from the current asset back to its source material.
 
-Ingredients themselves can be turned into ingredient archives (`.c2pa`). An ingredient archive is a serialized `Builder` with _exactly one_ ingredient. Once archived with only one ingredient, the Builder archive is an ingredient archive. Such ingredient archives can be used as ingredient in other working stores, as an ingredient archive can be added back directly to a working store (no un-archiving of the ingredient needed, use `application/c2pa` format when adding an ingredient archive to a Builder instance).
+The `relationship` field describes how the source (ingredient) was used: `"parentOf"` for a direct edit, `"componentOf"` for an element composited into a larger work, or `"inputTo"` for a general input.
+
+Ingredients themselves can be turned into ingredient archives (`.c2pa`). An ingredient archive is a `Builder` archive containing _exactly one_ ingredient. Ingredient archives can be added directly as an ingredient to another working store using the `application/c2pa` MIME type — no un-archiving step is needed.
 
 ### Adding ingredients to a working store
 
@@ -455,7 +445,7 @@ Specify the relationship between the ingredient and the current asset:
 | `componentOf` | The ingredient is a component used in this asset |
 | `inputTo` | The ingredient was an input to creating this asset |
 
-Example with explicit relationship (builder is created with a Context as in the examples above):
+Example with explicit relationship:
 
 ```py
 ingredient_json = json.dumps({
@@ -591,7 +581,7 @@ By default, manifest stores are **embedded** directly into the asset file. You c
 
 ### Default: embedded manifest stores
 
-By default, the  manifest store is embedded in the output asset.
+By default, the manifest store is embedded in the output asset.
 
 ```py
 ctx = Context.from_dict({"builder": {"thumbnail": {"enabled": True}}, "signer": signer})
@@ -644,43 +634,9 @@ with open("source.jpg", "rb") as src, open("output.jpg", "w+b") as dst:
 
 ## Best practices
 
-### Use Context for configuration
-
-Use `Context` objects for SDK configuration:
-
-```py
-ctx = Context.from_dict({
-    "verify": {
-        "verify_after_sign": True
-    },
-    "trust": {
-        "user_anchors": trust_anchors_pem
-    }
-})
-
-builder = Builder(manifest_json, context=ctx)
-reader = Reader("asset.jpg", context=ctx)
-```
-
-### Use ingredients to build provenance chains
-
-Add ingredients to your manifests to maintain a provenance chain:
-
-```py
-ctx = Context.from_dict({"builder": {"claim_generator_info": {"name": "my-app", "version": "0.1.0"}}, "signer": signer})
-builder = Builder(manifest_json, context=ctx)
-
-ingredient_json = json.dumps({
-    "title": "Original source",
-    "relationship": "parentOf"
-})
-
-with open("original.jpg", "rb") as ingredient:
-    builder.add_ingredient(ingredient_json, "image/jpeg", ingredient)
-
-with open("edited.jpg", "rb") as src, open("signed.jpg", "w+b") as dst:
-    builder.sign("image/jpeg", src, dst)
-```
+- **Use `Context` for all configuration.** Pass a `Context` to `Builder` and `Reader` rather than using global state. See [Context and settings](context-settings.md).
+- **Use ingredients to build provenance chains.** Add a `parentOf` ingredient whenever editing an existing asset. See [Working with ingredients](#working-with-ingredients).
+- **Never hard-code private keys in production.** Use a Hardware Security Module (HSM) or Key Management Service (KMS) to access credentials.
 
 ## Additional resources