docs: define generic provider mapping

Author: HaoZeke

README.md

@@ -118,6 +118,12 @@ build policy, and independently installable profiles live in package config.
 Each profile emits one `.eb` file; MPI/OpenMP toolchain options alone do not
 require a suffix.
 
+Aliases use `foreign = "EasyBuild"` when both names share a version domain.
+Component-to-provider mappings use
+`foreign = { provider = "EasyBuild", constraint = "drop" }`, so a component
+release such as a Python package version is never imposed on its containing
+EasyBuild provider.
+
 ```sh
 eb-stack package plan \
   --source fixtures/foreign_ingest/conda_eon/recipe.yaml \

docs/orgmode/explanation/architecture.org

@@ -39,6 +39,15 @@ variants, conflicts, requirements, source metadata, and source spans.
 Adapters do not choose EasyBuild dependency versions or emit placeholder
 recipes. Their output is package intent plus explicit residuals.
 
+* Provider mapping
+
+Layered package policy maps foreign dependency identities to EasyBuild
+providers after syntax parsing. Direct aliases preserve constraints when the
+two ecosystems use the same version domain. Component-to-provider aliases can
+drop a component constraint that has no meaning for the containing provider.
+The mapping is data, not parser control flow, and dependency provenance keeps
+the foreign evidence available for review.
+
 * Canonical package model
 
 ~PackagePlan~ is schema-versioned and shared by foreign imports and bumps. It

docs/orgmode/howto/new-package.org

@@ -65,8 +65,31 @@ eb-stack package inspect \
 A package layer can replace or extend parser-derived metadata without changing
 the parser. ~examples/packages/common.toml~ provides cross-ecosystem aliases;
 later layers may replace package metadata, build policy, aliases, virtuals,
-solver exclusions, and profiles. A QMCPACK profile set commonly contains a
-default MPI+OpenMP build and a separate ~-complex~ recipe:
+solver exclusions, and profiles.
+
+An alias maps a foreign dependency identity to an EasyBuild provider. Use the
+short string form when both names use the same version domain:
+
+#+begin_src toml
+[dependencies.aliases]
+libcurl = "cURL"
+#+end_src
+
+Use the structured form when the foreign dependency is a component supplied by
+a larger EasyBuild package. ~constraint = "drop"~ prevents the component's
+version from being interpreted as the provider's version:
+
+#+begin_src toml
+[dependencies.aliases]
+"py-setuptools" = { provider = "Python", constraint = "drop" }
+#+end_src
+
+The original foreign spelling and constraint remain in dependency provenance.
+Aliases only control robot matching and solving; they do not teach the parser
+about a package.
+
+A QMCPACK profile set commonly contains a default MPI+OpenMP build and a
+separate ~-complex~ recipe:
 
 #+begin_src toml
 schema_version = 1

skills/new-package/SKILL.md

@@ -31,6 +31,14 @@ use `[dependencies.virtuals]` for capabilities and
 `dependencies.exclude_from_solve` for foreign runtime metadata that remains
 visible in the manifest/SBOM but is not an EasyBuild dependency.
 
+Use `foreign = "EasyBuild"` only when the foreign component and EasyBuild
+provider share a version domain. When an EasyBuild package contains a foreign
+component, use
+`foreign = { provider = "EasyBuild", constraint = "drop" }`. This keeps a
+component release from becoming a false provider constraint while provenance
+retains the original foreign requirement. Do not repair this mismatch with a
+package-name parser branch.
+
 The `[package]` and `[build]` tables own EasyBuild spelling, release spelling,
 easyblock policy, module class, build options, and patches. `easyblock =
 "auto"` omits the parameter so EasyBuild can select a software-specific