docs: asset kinds and per-source asset aliases

docs/content/asset_modelling/engagements_tests/PRO__assets.md

@@ -174,6 +174,55 @@ Because Findings inherit risk, priority, and ownership from their parent Asset,
 
 Importantly, Assets are also the primary determining factor in a Finding’s SLA characteristics. Therefore, the SLA of a Findings depends on the SLA configuration of its parent Asset. More information about SLA configurations can be found [here](/asset_modelling/pro_hierarchy/priority_sla/#working-with-slas).
 
+## Asset Kinds
+
+An Asset can declare what kind of thing it is: a repository, a service, a host, a domain, a
+container image, a package, a cloud account, a device, or a branch. The kind is optional —
+an Asset without one behaves exactly as it always has — and it is descriptive rather than
+functional: it does not change permissions, deduplication, SLAs, or reporting scope. What it
+does is make a long Asset list readable, by giving each Asset an icon and a label that says
+what you are looking at.
+
+The list of kinds is data, not a fixed set. The kinds DefectDojo ships are marked as system
+kinds and cannot be deleted, but their wording and icons can be changed, and you can add your
+own kinds for anything your inventory contains that the shipped list does not cover.
+
+Kinds are available on the Asset itself and through the API at `/api/v2/asset_kinds/`
+(read-only) and as the `kind` field on `/api/v2/assets/`.
+
+## Asset Identity: Aliases
+
+The same Asset is usually known by different names in different places: a repository id in
+GitHub, a project key in your scanner, a hostname in DNS, an image digest in a registry. An
+**alias** records one of those identifiers against the Asset it refers to, so DefectDojo can
+recognise the Asset from whichever name a source happens to use.
+
+Each alias has three parts:
+
+- a **namespace**, naming the system that issued the identifier — `dns`, `oci`, `purl`, `git`,
+or a specific Connector configuration;
+- a **type**, saying what kind of identifier it is — `external_id`, `hostname`, `image_digest`,
+and so on;
+- the **value** itself.
+
+An identifier resolves to exactly one Asset. Two Assets cannot both claim `api.example.com` in
+the `dns` namespace, which is what makes an alias a reliable answer to "which Asset is this?"
+
+Aliases record where they came from. Ones you add yourself are marked as user-asserted and are
+never rewritten by automation; Connector sync maintains its own. That means you can correct a
+Connector's idea of what an identifier means without the next sync undoing it.
+
+Aliases are asserted or withdrawn, never edited: there is no update action on the API, because
+changing an identifier in place would silently re-point identity with no record of what it used
+to mean. To correct one, remove it and add the right one.
+
+Connector-issued aliases are written by Connector sync rather than by hand, so the API refuses
+writes to a `connector:` namespace. Everything else is yours to declare, through
+`/api/v2/asset_aliases/`.
+
+Aliases require `DD_V3_ASSET_ALIASES` to be enabled before they can be created; existing ones
+stay readable whether it is on or off.
+
 ## Asset Nesting
 
 DefectDojo supports parent-child relationship between two Assets within the same Organization. This can be configured during Asset creation or in the Asset’s settings. 

docs/content/connectors/upstream/manage_records.md

@@ -37,6 +37,32 @@ If you have **Auto-Mapping** enabled, new Records will be Mapped to Products aut
 
 If you don't have Auto-Mapping enabled, you can make your own decisions about where you want data to flow. Each time the Connector finds a new Vendor-Equivalent Product (via **Discover**), it will add a new Record to your **Unmapped Records** list, and you can then manually assign that Record to a new or existing Product in DefectDojo.
 
+#### How Auto-Mapping chooses the Product
+
+Auto-Mapping resolves each Record in a fixed order, and stops at the first answer:
+
+1. **The tool's own identifier.** Every Record stores the identifier the tool uses for the
+Vendor-Equivalent Product. Once a Connector has mapped that identifier once, it recognises it
+on every later Discover — so renaming the project in the tool, or in DefectDojo, no longer
+loses the Mapping or creates a duplicate Product.
+2. **The name.** If the Connector has not seen the identifier before, it looks for a Product
+whose name matches. When one is found, the Record is mapped to it and the identifier is
+recorded, so step 1 answers from then on.
+3. **A new Product.** If neither matches, DefectDojo creates one.
+
+Step 1 requires the identity feature to be enabled (`DD_V3_ASSET_ALIASES`); until then,
+Auto-Mapping resolves by name alone, which is the historical behaviour. Enabling it changes
+nothing about existing Mappings: the first Discover after it is turned on records identifiers
+for the Records you already have, and later runs use them.
+
+Because names are matched globally, two tools that each report something called `payments` map
+to the same Product on first sight. Recording each tool's identifier separately is what stops
+that coincidence from becoming permanent — after the first mapping, each Connector follows its
+own identifier rather than the shared name.
+
+Remapping a Record by hand always wins. When you change a Record's Mapping yourself, the
+tool's identifier moves with it, and the next sync follows your decision.
+
 #### Mapping - Example Workflow:
 
 David has just finished setting up a connector for his BurpSuite tool, and runs a Discover operation. David has Burp set up to scan 4 different 'Sites', and DefectDojo creates a new Record for each of those Sites.