Document org name normalization across language ecosystems

Add "Organization Name Normalization" section to multi-language strategy
docs showing how hyphenated/mixed-case org names are translated per
ecosystem (Python imports, Rust modules, C++ namespaces, Java packages,
Docker images). Include a full derivation table for org=Acme-Corp.

Cross-reference from the configuration reference org field and add a
normalization checklist to the plugin CONTRIBUTING guide so new language
authors handle dashes correctly.

Author: daniel-garcia

docs/cli-reference/configuration.md

@@ -35,7 +35,7 @@ version: 1
 | Field     | Type   | Description                    |
 |-----------|--------|--------------------------------|
 | `version` | integer | Schema version number         |
-| `org`     | string  | GitHub organization name      |
+| `org`     | string  | GitHub organization name (hyphens and mixed case are normalized per-language; see [Org Name Normalization](../concepts/multi-language-strategy.md#organization-name-normalization)) |
 | `repo`    | string  | Canonical API repository name |
 
 ## Complete Field Reference

docs/concepts/multi-language-strategy.md

@@ -30,6 +30,37 @@ Given `org=acme` and API path `proto/payments/ledger/v1`:
 ```{include} ../_generated/identity-derivation-table.md
 ```
 
+## Organization Name Normalization
+
+The `org` value from `apx.yaml` flows into every derived coordinate. Because each language ecosystem has its own identifier rules, APX normalizes the org name per-language:
+
+| Context | Rule | `Acme-Corp` becomes |
+|---------|------|---------------------|
+| **Package manager names** (PyPI dist, Cargo crate, Conan ref, npm scope) | Lowercase only — hyphens are valid | `acme-corp` |
+| **OCI / Docker image refs** | Must be fully lowercase | `acme-corp` |
+| **Go module paths** | Case-insensitive (Git hosting) | `acme-corp` |
+| **Python imports** | Hyphens → underscores (Python identifiers) | `acme_corp_apis` |
+| **Rust module paths** | Hyphens → underscores (Rust identifiers) | `acme_corp_` |
+| **C++ namespaces** | Hyphens → underscores (C++ identifiers) | `acme_corp::` |
+| **Java packages** | Hyphens → dots (reverse-domain convention) | `com.acme.corp.apis` |
+
+Given `org=Acme-Corp` and API path `proto/payments/ledger/v1`:
+
+| Coordinate | Derived Value |
+|------------|---------------|
+| Go module | `github.com/Acme-Corp/apis/proto/payments/ledger` |
+| Py dist | `acme-corp-payments-ledger-v1` |
+| Py import | `acme_corp_apis.payments.ledger.v1` |
+| Crate | `acme-corp-payments-ledger-v1-proto` |
+| Rust mod | `acme_corp_payments::ledger::v1` |
+| Conan | `acme-corp-payments-ledger-v1-proto` |
+| C++ ns | `acme_corp::payments::ledger::v1` |
+| Maven | `com.acme.corp.apis:payments-ledger-v1-proto` |
+| Java pkg | `com.acme.corp.apis.payments.ledger.v1` |
+| npm | `@acme-corp/payments-ledger-v1-proto` |
+
+**Key takeaway:** Hyphens in org names are fine. APX handles the per-ecosystem translation automatically. You never need to pre-normalize your org name.
+
 ## Go Workflow
 
 Go is the Tier 1 language with the most mature overlay system:

internal/language/CONTRIBUTING.md

@@ -11,6 +11,17 @@ the release manifest.
 - Understand the APX API identity model (format/domain/name/line)
 - Know how the target language's package ecosystem works (naming, imports, registries)
 
+## Org Name Normalization
+
+The `org` value may contain hyphens (`acme-corp`) or mixed case (`Acme-Corp`).
+Your derivation functions **must** handle this correctly:
+
+- **Package manager names** (crate, dist, npm scope) — lowercase only; hyphens are usually valid
+- **Language identifiers** (imports, modules, namespaces) — hyphens are typically invalid; replace with underscores or dots per the target language's rules
+
+See existing plugins for patterns: Python (`_apis` namespace), Rust (`_` join),
+C++ (`_` replace), Java (hyphens → dots). Tests must include a `"hyphenated org"` case.
+
 ## Step-by-Step Checklist
 
 ### 1. Plugin Implementation (with Derivation)