Add centralized repository documentation

.gitignore

@@ -1,3 +1,5 @@
 node_modules
 docs/.vitepress/dist
 docs/.vitepress/cache
+.vitepress/cache
+.DS_Store

README.md

@@ -1 +1,37 @@
 # postguard-docs
+
+> For full documentation, visit [docs.postguard.eu](https://docs.postguard.eu).
+
+The central documentation site for the PostGuard project. Built with [VitePress](https://vitepress.dev/) and hosted at [docs.postguard.eu](https://docs.postguard.eu).
+
+This site contains guides, SDK reference documentation, integration instructions, and per-repository documentation for all repos in the [encryption4all](https://github.com/encryption4all) organization.
+
+## Development
+
+### Prerequisites
+
+- Node.js 18+
+
+### Running Locally
+
+```bash
+npm install
+npm run docs:dev
+```
+
+The dev server starts with hot reload at `http://localhost:5173`.
+
+### Building
+
+```bash
+npm run docs:build
+npm run docs:preview   # preview the built site
+```
+
+## Releasing
+
+The site is deployed automatically via GitHub Actions. Pushing to `main` triggers a Docker image build (NGINX-based static hosting) which is deployed to production.
+
+## License
+
+MIT

docs/.vitepress/config.mts

@@ -9,7 +9,7 @@ export default defineConfig({
     nav: [
       { text: 'Guide', link: '/guide/what-is-postguard' },
       { text: 'SDK', link: '/sdk/overview' },
-      { text: 'Integrations', link: '/integrations/web-app' },
+      { text: 'Repositories', link: '/repos/overview' },
     ],
     sidebar: [
       {
@@ -19,25 +19,76 @@ export default defineConfig({
           { text: 'Usage Flows', link: '/guide/usage-flows' },
           { text: 'Core Concepts', link: '/guide/concepts' },
           { text: 'Architecture', link: '/guide/architecture' },
-          { text: 'Getting Started', link: '/guide/getting-started' },
+          { text: 'Protocol Specification', link: '/guide/protocol' },
         ],
       },
       {
         text: 'SDK Reference',
         items: [
           { text: 'Overview', link: '/sdk/overview' },
-          { text: 'Encryption', link: '/sdk/encryption' },
-          { text: 'Decryption', link: '/sdk/decryption' },
-          { text: 'Email Helpers', link: '/sdk/email-helpers' },
-          { text: 'Authentication Methods', link: '/sdk/auth-methods' },
-          { text: 'Error Handling', link: '/sdk/errors' },
+          { text: 'Getting Started', link: '/sdk/getting-started' },
+          {
+            text: 'JavaScript SDK',
+            collapsed: false,
+            items: [
+              { text: 'Encryption', link: '/sdk/js-encryption' },
+              { text: 'Decryption', link: '/sdk/js-decryption' },
+              { text: 'Email Helpers', link: '/sdk/js-email-helpers' },
+              { text: 'Authentication Methods', link: '/sdk/js-auth-methods' },
+              { text: 'Error Handling', link: '/sdk/js-errors' },
+            ],
+          },
+          {
+            text: '.NET SDK',
+            collapsed: false,
+            items: [
+              { text: 'Encryption', link: '/sdk/dotnet-encryption' },
+              { text: 'Error Handling', link: '/sdk/dotnet-errors' },
+            ],
+          },
         ],
       },
       {
-        text: 'Integrations',
+        text: 'Repositories',
         items: [
-          { text: 'Web Application', link: '/integrations/web-app' },
-          { text: 'Email Addon', link: '/integrations/email-addon' },
+          { text: 'Overview', link: '/repos/overview' },
+          {
+            text: 'Cryptographic Libraries',
+            collapsed: false,
+            items: [
+              { text: 'pg-curve', link: '/repos/pg-curve' },
+              { text: 'ibe', link: '/repos/ibe' },
+              { text: 'ibs', link: '/repos/ibs' },
+            ],
+          },
+          {
+            text: 'Core',
+            collapsed: false,
+            items: [
+              { text: 'postguard', link: '/repos/postguard' },
+              { text: 'postguard-website', link: '/repos/postguard-website' },
+              { text: 'cryptify', link: '/repos/cryptify' },
+              { text: 'postguard-tb-addon', link: '/repos/postguard-tb-addon' },
+              { text: 'postguard-outlook-addon', link: '/repos/postguard-outlook-addon' },
+            ],
+          },
+          {
+            text: 'SDKs',
+            collapsed: false,
+            items: [
+              { text: 'postguard-js', link: '/repos/postguard-js' },
+              { text: 'postguard-dotnet', link: '/repos/postguard-dotnet' },
+              { text: 'pg-components', link: '/repos/pg-components' },
+            ],
+          },
+          {
+            text: 'postguard-examples',
+            collapsed: false,
+            items: [
+              { text: 'pg-sveltekit', link: '/repos/pg-sveltekit' },
+              { text: 'pg-dotnet', link: '/repos/pg-dotnet' },
+            ],
+          },
         ],
       },
     ],

docs/guide/architecture.md

@@ -58,6 +58,28 @@ IBS Master Key Pair (lives on the PKG server)
         Used to derive per-sender signing keys
 ```
 
+## Session Flow
+
+A typical PostGuard session works as follows. Red actions require user interaction; all other actions are automatic.
+
+<p align="center">
+  <img src="/postguard-flow.png" alt="PostGuard session flow"/>
+</p>
+
+0. The PKG generates a master key pair.
+1. Alice's client retrieves the public master key from the PKG.
+2. Alice uses the public master key and Bob's identity to encrypt a message.
+3. Alice's client sends the ciphertext to Bob via any channel.
+4. Bob's client asks for a key to decrypt the ciphertext.
+5. The PKG starts an authentication session at the Yivi server.
+6. Bob is asked to reveal his identity via a QR code.
+7. Bob reveals his identity.
+8. The Yivi server sends the authentication results to the PKG.
+9. The PKG issues a key for Bob's identity.
+10. Bob's client decrypts the ciphertext using his key.
+
+The sections below break down the encryption and decryption steps in more detail.
+
 ## Encryption Flow
 
 Here is what happens when a sender encrypts data:

docs/guide/concepts.md

@@ -26,9 +26,9 @@ The sender never needs to look anything up or coordinate with the recipient. Enc
 
 ### Cryptographic details
 
-PostGuard uses the CGW Anonymous IBE scheme (variant CGWKV) with multi-recipient key encapsulation (MKEM), built on the BLS12-381 elliptic curve. This provides approximately 120-bit security. Identities are derived by hashing policies (attribute types, values, and a timestamp) with SHA3-512 using domain separation.
+PostGuard uses the CGW Anonymous IBE scheme (variant CGWKV) with multi-recipient key encapsulation (mIBKEM), built on the BLS12-381 elliptic curve. This provides approximately 128 bits of security. Identities are derived by hashing policies (attribute types, values, and a timestamp) with SHA3-512 using domain separation. See the [identity derivation algorithm](/guide/protocol#mapping-yivi-identities-to-ibc-identities) for the exact procedure.
 
-Symmetric encryption uses AES-128-GCM (matching the BLS12-381 security level). The SDK supports both in-memory and streaming encryption, with streaming using 256 KiB chunks by default.
+Symmetric encryption uses AES-128-GCM (matching the BLS12-381 security level). The SDK supports both in-memory and streaming encryption, with streaming using 256 KiB chunks and per-segment signatures by default. For the full cryptographic specification, see the [protocol specification](/guide/protocol).
 
 ## PKG (Private Key Generator)
 
@@ -228,8 +228,10 @@ PAYLOAD (variable)
   (includes message signature for authentication)
 ```
 
-The header contains one entry per recipient, each with the recipient's hidden policy (attribute types visible, values redacted) and a multi-recipient ciphertext. The payload contains the actual encrypted data with a sign-then-encrypt composition.
+The header contains one entry per recipient, each with the recipient's hidden policy (attribute types visible, values redacted) and a multi-recipient ciphertext. The payload contains the actual encrypted data with a Sign-then-Encrypt composition.
+
+For the full wire format diagrams (in-memory and streaming mode), JSON header examples, and the email MIME format, see the [protocol specification](/guide/protocol#wire-format).
 
 ## Next steps
 
-Now that you understand the concepts, see the [architecture overview](/guide/architecture) to learn how these components connect and communicate.
+Now that you understand the concepts, see the [architecture overview](/guide/architecture) to learn how these components connect and communicate, or the [protocol specification](/guide/protocol) for the full cryptographic details.