Replace Credential Formats section with Credential Engine detailed design

docs/wallet-architecture/02-credential-engine/credential-parsing.md

@@ -0,0 +1,54 @@
+# Credential Parsing
+
+A parser is responsible for recognizing a credential format and transforming it into a common `ParsedCredential` structure.
+
+The normalized model contains:
+
+* Credential metadata
+* Issuer information
+* Validity information
+* Signed claims
+* Display metadata and warnings
+
+By exposing a common representation, wallet features can operate independently of the underlying credential format.
+
+## Parser Selection
+
+Parsers are registered with the `ParsingEngine`.
+
+When a credential is parsed, the engine invokes registered parsers until one successfully recognizes and parses the credential. This allows multiple credential formats to coexist within the same wallet while keeping format-specific logic isolated within each parser implementation.
+
+### Unsupported Formats
+
+A parser should only handle credentials that belong to its supported format.
+
+If a parser determines that a credential is not of the expected format, it should return an `UnsupportedFormat` parsing error so that the next registered parser can attempt to process the credential.
+
+This allows multiple credential formats to coexist within the same `ParsingEngine` while keeping format-specific detection logic isolated within each parser implementation.
+
+## Credential Display Metadata
+
+Credential formats often contain only the information required for cryptographic verification.
+
+To support a richer user experience, parsers may resolve and expose display metadata such as:
+
+* Human-readable credential names
+* Localized labels
+* Claim descriptions
+* Credential images
+* SVG templates and rendering information
+
+This metadata is surfaced through the normalized credential model and can originate from format-specific metadata registries or external resolution services.
+
+### Metadata Sources
+
+Display metadata may originate from different sources depending on the credential format and deployment configuration.
+
+Common sources include:
+
+- [OID4VCI Credential Issuer Metadata](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html#name-credential-issuer-metadata)
+- [SD-JWT VC Type Metadata (VCT Metadata)](https://www.ietf.org/archive/id/draft-ietf-oauth-sd-jwt-vc-16.html#name-display-metadata) for the `dc+sd-jwt` credential format.
+- Format-specific registries (example, [wwWallet's VCT Registry](https://www.ietf.org/archive/id/draft-ietf-oauth-sd-jwt-vc-16.html#name-display-metadata)  for `dc+sd-jwt` VCs.)
+- Application-defined metadata overrides
+
+Applications may also provide custom metadata for specific issuers or credential types when display metadata is unavailable from standard sources.

docs/wallet-architecture/02-credential-engine/credential-verification.md

@@ -0,0 +1,29 @@
+# Credential Verification
+
+Verification is intentionally separate from parsing.
+
+A credential may be successfully parsed but still fail verification due to invalid signatures, expired validity periods, missing trust anchors, or format-specific validation failures.
+
+Verifiers are responsible for:
+
+* Signature validation
+* Issuer trust validation
+* Public key resolution
+* Validity period checks
+* Format-specific security requirements
+
+The verification result is intentionally format-agnostic, allowing higher-level wallet workflows to treat all credential formats consistently.
+
+## Public Key Resolution
+
+Many credential formats require external public keys for signature verification.
+
+The Credential Engine provides a dedicated public key resolution framework that can be extended to support different trust infrastructures, including:
+
+* DID Documents
+* JWKS endpoints
+* OpenID-based metadata
+* Trusted registries
+* Proprietary trust systems
+
+Resolvers are independent of credential formats and can be reused across multiple verifiers.

docs/wallet-architecture/02-credential-engine/index.md

@@ -0,0 +1,43 @@
+---
+sidebar_position: 2
+---
+# Credential Engine
+
+The Credential Engine provides a pluggable framework for supporting multiple Verifiable Credential formats. Each format is integrated through two independent components:
+
+* **[Credential Parser](./credential-parsing)**  — Converts a raw credential into the wallet's normalized credential model.
+* **[Credential Verifier](./credential-verification)** — Validates the authenticity and integrity of a credential.
+
+This separation allows new credential formats to be added without changing the core engine.
+
+## Currently Supported Formats
+
+| Name                 | Format      | Parser          | Verifier          |
+| -------------------- | ----------- | --------------- | ----------------- |
+| SD-JWT VC            | `dc+sd-jwt` | `SDJWTVCParser` | `SDJWTVCVerifier` |
+| ISO/IEC 23220-1:2023 | `mso_mdoc`  | `MsoMdocParser` | `MsoMdocVerifier` |
+
+Both parsers and verifiers are registered during credential engine initialization.
+
+## Extending the Framework
+
+Supporting a new credential format typically requires:
+
+1. Implementing a `CredentialParser`
+2. Implementing a `CredentialVerifier`
+3. Registering the parser with the `ParsingEngine`
+4. Exposing the verifier through the application
+
+Once registered, the new format becomes a first-class participant in credential issuance, storage, display, presentation, and verification workflows without requiring changes to existing format implementations.
+
+## Design Principles
+
+The framework is built around a few core principles:
+
+* **Format Independence** — Wallet features operate on a normalized credential model.
+* **Separation of Concerns** — Parsing and verification are independent operations.
+* **Pluggability** — New formats can be added through registration.
+* **Extensibility** — Metadata and trust infrastructure can be customized.
+* **Interoperability** — Multiple credential formats can coexist within the same deployment.
+
+This approach allows the Credential Engine to support evolving credential standards while providing a consistent integration experience for developers.