docs: add SCOPE.md for rapid orientation

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

SCOPE.md

@@ -0,0 +1,97 @@
+# SCOPE
+
+> This file helps you quickly understand what this repository is about,
+> when it is relevant, and when it is not.
+> It is intentionally lightweight and may be incomplete.
+
+---
+
+## One-liner
+
+Lightweight IAM implementation of the NetKingdom IAM Profile — orchestrates Authelia, LLDAP, and privacyIDEA to provide OIDC/PKCE authentication as a drop-in Keycloak alternative.
+
+---
+
+## Core Idea
+
+NetKingdom applications target the "NetKingdom IAM Profile" — a versioned OIDC/PKCE contract. KeyCape implements that profile in lightweight mode (Authelia + LLDAP + privacyIDEA) with intentional constraints: no implicit flow, no wildcard redirects, no dynamic client registration. The same profile is implemented in expanded mode by Keycloak, so applications can migrate between modes without code changes.
+
+---
+
+## In Scope
+
+- OIDC profile endpoints (discovery, authorization, token, JWKS, userinfo) per NetKingdom IAM Profile
+- Canonical identity model: users, groups, clients, MFA
+- Claim normalization across Authelia/LLDAP/privacyIDEA backend quirks
+- Profile enforcement with structured error taxonomy (no silent emulation of unsupported features)
+- Telemetry for unsupported-feature requests
+- Migration tooling: LLDAP export, Keycloak import, LDIF generation
+- LDAP schema validation
+- Full acceptance test suite (profile baseline, migration scenarios, negative tests)
+
+---
+
+## Out of Scope
+
+- General-purpose IAM (profile-specific only; no out-of-profile extensions)
+- Dynamic client registration
+- Implicit flow
+- Wildcard redirect URIs
+- Identity brokering beyond OIDC
+- Keycloak operations (KeyCape is the lightweight alternative, not a Keycloak wrapper)
+
+---
+
+## Relevant When
+
+- Deploying NetKingdom IAM in lightweight mode (no Keycloak license/resources needed)
+- Applications need OIDC authentication with MFA in a constrained environment
+- Migrating from lightweight (KeyCape) to expanded (Keycloak) mode
+- Validating LDAP schema or generating migration artifacts
+
+---
+
+## Not Relevant When
+
+- Expanded-mode Keycloak is already running (applications use the same profile; no code changes needed)
+- Need out-of-profile IAM features (dynamic client registration, implicit flow, etc.)
+- Non-NetKingdom OIDC deployments
+
+---
+
+## Current State
+
+- Status: stable (v0.1 complete)
+- Implementation: complete — all 23 workplan tasks implemented and tested
+- Stability: high — profile-constrained; no silent failures; acceptance tests passing
+- Usage: internal NetKingdom stack; replaces Keycloak in lightweight deployments
+
+---
+
+## How It Fits
+
+- Upstream dependencies: Authelia (OIDC provider/sessions), LLDAP (identity directory), privacyIDEA (MFA)
+- Downstream consumers: all NetKingdom applications; net-kingdom (parent domain)
+- Often used with: net-kingdom (SSO/MFA workplan), railiance (deployed on Railiance infrastructure)
+
+---
+
+## Terminology
+
+- Preferred terms: NetKingdom IAM Profile, lightweight mode, expanded mode, profile enforcement, canonical model
+- Also known as: "KeyCape", "key-cape"
+- Potentially confusing terms: "lightweight mode" = KeyCape stack; "expanded mode" = Keycloak stack; both implement the same OIDC profile
+
+---
+
+## Related / Overlapping Repositories
+
+- `net-kingdom` — parent platform domain; KeyCape is the lightweight IAM implementation of its IAM Profile
+
+---
+
+## Getting Oriented
+
+- Start with: `wiki/KeyCapeSpecification_v0.1.md` (architecture and design intent)
+- Key files / directories: `wiki/KeyCapeSpecificationPack_v0.1.md` (normative spec), `src/cmd/` (binary entrypoints), `src/internal/` (implementation), `tests/` (acceptance suite)
+- Entry points: `keycape server` binary; `keycape migrate` for migration tooling