feat: add subject mapping guide

.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,11 +20,21 @@ assertation
 [Dd]issem
 JavaScript
 Autoconfigure
-requester(?('s))
-rewrap(?(s))
+requester('s)?
+rewraps?
 ERS
 APIs
 JWTs
 protos
 decisioning
-failover
+failover
+CI
+[Ss]hellcheck
+Okta
+[Bb]oolean
+[Ss]ubstrings?
+walkthrough
+enum
+OR'd
+NPEs
+top_secret

AGENTS.md

@@ -20,7 +20,7 @@
 
 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 +30,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`
 
 ## Preview Deployment
 

docs/components/entity_resolution.md

@@ -1,6 +1,26 @@
 # Entity Resolution Service
 
-The Entity Resolution Service (ERS) is an IdP-specific service that interacts with the Identity Provider (IdP) to retrieve information about entities required by the Authorization service.
+The Entity Resolution Service (ERS) is a platform-internal service that produces **Entity Representations** — normalized views of an entity's identity attributes — for use by the Authorization Service when evaluating Subject Mappings.
+
+ERS is bundled into the platform and runs automatically as part of the default deployment (`mode: all`). There is no separate ERS service to set up.
+
+:::note Keycloak as IdP vs. Keycloak ERS
+These are two different things:
+- **Keycloak as IdP**: authenticates users and issues JWT tokens. This is always external to the platform.
+- **Keycloak ERS mode**: after receiving a token, ERS calls the Keycloak **Admin API** to fetch additional user data (custom attributes, groups, roles) that may not be in the JWT. This is one of three available ERS modes.
+
+You can use Keycloak as your IdP without using Keycloak ERS mode — configure `mode: claims` and ERS will use JWT claims directly without calling back to Keycloak.
+:::
+
+:::note Entity categories and Subject Mappings
+ERS categorizes entities from a token as either:
+- **`CATEGORY_SUBJECT`** (users): evaluated against Subject Mappings to determine entitlements
+- **`CATEGORY_ENVIRONMENT`** (OIDC clients / service accounts): tracked in audit logs but **not** evaluated in access decisions
+
+In a standard user-auth flow, the user is `CATEGORY_SUBJECT` and the OIDC client is `CATEGORY_ENVIRONMENT`. In a client credentials (service account) flow with no human user, the client itself becomes `CATEGORY_SUBJECT` and requires its own Subject Mappings.
+
+Note: Claims ERS categorizes all entities as `CATEGORY_SUBJECT`. Keycloak ERS distinguishes between users and clients.
+:::
 
 ## Built-In Entity Resolution Services
 

docs/components/policy/subject_mappings.md

@@ -1,5 +1,13 @@
 # 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 Guide](/guides/subject-mapping-guide).
+:::
+
+:::note What Subject Mappings evaluate against
+Subject Mappings evaluate conditions against an **Entity Representation** produced by the [Entity Resolution Service (ERS)](/components/entity_resolution) — not directly against raw IdP tokens. Depending on which ERS mode is configured, this representation may include JWT claims from the token, enriched user data from the Keycloak Admin API, or data from external sources such as LDAP or SQL. The fields available to your selectors depend on [which mode is configured](/components/entity_resolution).
+:::
+
 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."
+  }
+}