feat: DSPX-2416 add subject mapping guide

.github/vale-styles/config/Vocab/Opentdf/accept.txt

@@ -0,0 +1,27 @@
+Docusaurus
+[Oo]tdfctl
+API
+(?i:tdf)
+[Nn]amespace
+Keycloak
+Virtru
+SDK
+IdP
+NPE
+PE
+FQN
+JWT
+proto
+Postgres
+ECDSA
+[Nn]ano
+Podman
+assertation
+[Dd]issem
+JavaScript
+Autoconfigure
+requester('s)?
+rewraps?
+CI
+[Ss]hellcheck
+Okta

.github/vale-styles/config/vocabularies/Opentdf/accept.txt

@@ -1,7 +1,7 @@
 Docusaurus
 [Oo]tdfctl
 API
-(?i)tdf
+(?i:tdf)
 [Nn]amespace
 Keycloak
 Virtru
@@ -20,5 +20,8 @@ assertation
 [Dd]issem
 JavaScript
 Autoconfigure
-requester(?('s))
-rewrap(?(s))
+requester('s)?
+rewraps?
+CI
+[Ss]hellcheck
+Okta

AGENTS.md

@@ -18,9 +18,13 @@
 - `npm run check-vendored-yaml`: Verify vendored OpenAPI YAML matches upstream.
 - `npm run update-vendored-yaml`: Refresh vendored specs in `specs/` from upstream.
 
+Preview deployment:
+- Deploy to preview using pattern: `surge build opentdf-docs-preview-<ticket>.surge.sh`
+- Extract ticket number from branch name (e.g., branch `feat/dspx-2416` → `opentdf-docs-preview-dspx-2416.surge.sh`)
+
 Docs-only checks:
 - `vale sync`: Install Vale styles configured in `.vale.ini`.
-- `git diff --name-only | xargs vale --glob='!blog/*'`: Lint changed docs (matches CI’s “added lines” behavior closely).
+- `git diff --name-only | xargs vale --glob='!blog/*'`: Lint changed docs (matches CI's "added lines" behavior closely).
 
 ## Coding Style & Naming Conventions
 
@@ -30,8 +34,18 @@ Docs-only checks:
 
 ## Testing Guidelines
 
-- There is no dedicated unit test runner; CI primarily validates `npm run build` and Vale.
-- If you touch `docs/getting-started/` Docker Compose instructions, sanity-check them locally when feasible.
+CI runs the following tests:
+
+- **BATS tests**: Shell script tests in `tests/quickstart.bats` validate quickstart scripts on Ubuntu, macOS, and Windows
+- **Shellcheck**: Lints shell scripts in `static/quickstart/` (check.sh, install.sh)
+- **Docker Compose stack test**: Verifies the platform starts successfully on Ubuntu (triggered by changes to `docs/getting-started/`, `static/quickstart/`, or `tests/`)
+- **Build validation**: `npm run build` must complete successfully
+- **Vale linting**: Documentation prose style checks (run locally with `git diff --name-only | xargs vale --glob='!blog/*'`)
+
+If you modify quickstart scripts or Docker Compose instructions:
+- Run shellcheck locally: `shellcheck static/quickstart/check.sh static/quickstart/install.sh`
+- Run BATS tests if available: `bats tests/quickstart.bats`
+- Test the Docker Compose stack if feasible: Follow steps in `docs/getting-started/quickstart.mdx`
 
 ## Commit & Pull Request Guidelines
 

docs/components/policy/subject_mappings.md

@@ -1,5 +1,19 @@
 # Subject Mappings
 
+:::tip New to Subject Mappings?
+For a comprehensive tutorial with IdP integration examples, troubleshooting, and step-by-step guides, see the [Subject Mapping Comprehensive Guide](/guides/subject-mapping-guide).
+:::
+
+:::note Entity attributes come from the Entity Resolution Service (ERS)
+Subject Mappings evaluate conditions against the **Entity Representation** produced by the Entity Resolution Service — not directly against IdP tokens. Depending on ERS configuration, entity attributes may come from:
+- Access token claims (JWT)
+- IdP user info (e.g., Keycloak, Okta)
+- LDAP / Active Directory
+- SQL databases
+
+This means a Subject Condition Set matching `.emailAddress` will work regardless of whether that attribute comes from a JWT claim, an LDAP directory entry, or a SQL row — as long as ERS resolves it into the entity representation. Multi-source ERS support is available; see the [Entity Resolution](/components/entity_resolution) documentation.
+:::
+
 As data is bound to fully qualified Attribute Values when encrypted within a TDF, entities are associated with Attribute values through a mechanism called Subject Mappings.
 
 Entities (subjects, users, machines, etc.) are represented by their identity as determined from an identity provider (IdP). After an entity has securely authenticated with the IdP, the client's token (OIDC/OAUTH2) will include claims or attributes that describe that identity. Subject Mappings define how to map these identity attributes to actions on attribute values defined in the OpenTDF platform Policy. For more details on how the platform integrates with the IdP and how entities are resolved, refer to the [Authorization documentation](../authorization).

docs/guides/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Guides",
+  "position": 3,
+  "link": {
+    "type": "generated-index",
+    "description": "Comprehensive guides and tutorials for implementing OpenTDF features."
+  }
+}