Clarify id_field and parent_field semantics in docs

.github/workflows/benchmark.yml

@@ -5,6 +5,11 @@ on:
     branches: [ main ]
   pull_request:
     branches: [ main ]
+    paths:
+      - 'src/**'
+      - 'tests/**'
+      - 'scripts/**'
+      - 'pyproject.toml'
   workflow_dispatch:
 
 jobs:

.github/workflows/main.yml

@@ -5,6 +5,11 @@ on:
     branches: [ main ]
   pull_request:
     branches: [ main ]
+    paths:
+      - 'src/**'
+      - 'tests/**'
+      - 'scripts/**'
+      - 'pyproject.toml'
   workflow_dispatch:
 
 jobs:

docs/configuration.md

@@ -115,15 +115,34 @@ These parameters have sensible defaults and rarely need adjustment.
 **Type:** `str`
 **Default:** `"_id"`
 
-Field name for record IDs. Change only if `_id` conflicts with your data schema.
+Controls two things depending on `id_generation`:
+
+- **Output field name** — the name of the ID field written to every output record,
+  regardless of strategy.
+- **Source field name** — when `id_generation="natural"`, the field transmog reads
+  from each source record to use as that record's ID.
+
+For all other strategies (`"random"`, `"hash"`, composite list), the value is only
+used as the output field name — no source field is read.
+
+Change this only if `_id` conflicts with your data schema.
 
 ### parent_field
 
 **Type:** `str`
 **Default:** `"_parent_id"`
 
-Field name for parent references in child tables. Change only if `_parent_id`
-conflicts with your data schema.
+Controls the **output field name** written on child records to reference their
+parent's ID. This is purely an output concern — it does not read from or target
+any field in the source data. The parent-child link is established automatically
+from the nesting structure.
+
+Change this only if `_parent_id` conflicts with your data schema.
+
+:::{note}
+`id_field`, `parent_field`, and `time_field` must all be distinct. Supplying the
+same name for any two raises a `ConfigurationError`.
+:::
 
 ### time_field
 

docs/ids.md

@@ -85,7 +85,12 @@ assert result1.main[0]["_id"] == result2.main[0]["_id"]
 
 ## Metadata Field Names
 
-Customize the names of metadata fields:
+`id_field`, `parent_field`, and `time_field` control the **names of metadata
+columns in the output**. They do not affect how source data is read, with one
+exception: `id_field` doubles as the source field name when
+`id_generation="natural"` (see [Natural IDs](#natural-ids) above).
+
+Customize these names when the defaults conflict with your data schema:
 
 ```python
 config = tm.TransmogConfig(
@@ -100,6 +105,9 @@ print(result.main[0])
 # {'name': 'Product', 'record_id': '...', '_created_at': '...'}
 ```
 
+All three names must be distinct. Supplying the same value for any two raises a
+`ConfigurationError`.
+
 Disable timestamp tracking:
 
 ```python
@@ -109,7 +117,9 @@ result = tm.flatten(data, config=config)
 
 ## Parent-Child Relationships
 
-Child records reference their parents through the parent ID field:
+Child records reference their parents through the `parent_field` output column.
+This link is built automatically from the nesting structure — no configuration
+beyond the field name is required.
 
 ```python
 result = tm.flatten(data, name="products")