docs: build complete MAVULA API portal

.gitignore

@@ -1,5 +1,9 @@
 node_modules/
 dist/
+.astro/
+.playwright/
+playwright-report/
+test-results/
 .redocly/
 *.log
 .env

README.md

@@ -1,13 +1,14 @@
-# MAVULA Developer Documentation
+# MAVULA Developer Docs
 
-Versioned public API contracts and developer documentation for MAVULA.
+Public integration guides and versioned API contracts for MAVULA financial infrastructure.
 
 The repository publishes approved Identity Access, Ledger Core and Workbench
 interfaces. Internal callbacks, health checks and observability endpoints are
 excluded from the public reference.
 
-The legacy batch guide documents regulatory export generation, validation-only
-imports, durable receipts, delivery registration and operator recovery.
+The Astro and Starlight portal covers identity, tenant isolation, account and
+financial controls, payment jobs, configuration, projections and legacy batch
+operations. Scalar renders the three public OpenAPI contracts locally.
 
 ## Contracts
 
@@ -25,8 +26,12 @@ pnpm guardian:check
 pnpm contracts:check
 pnpm test
 pnpm build
+pnpm test:e2e
 ```
 
+Run `pnpm dev` for local authoring. The production site is published from
+GitHub Actions to `https://mavulahq.github.io/developer-docs/`.
+
 ## License
 
 AGPL-3.0-only. MAVULA names and marks remain reserved.

astro.config.mjs

@@ -0,0 +1,80 @@
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+
+const sidebar = [
+  { label: 'Home', link: '/' },
+  {
+    label: 'Get started',
+    items: [
+      { label: 'Overview', link: '/v1/' },
+      { label: 'Quickstart', link: '/v1/getting-started/quickstart/' },
+      { label: 'Authentication', link: '/v1/getting-started/authentication/' },
+      { label: 'Roles and permissions', link: '/v1/getting-started/roles-permissions/' },
+      { label: 'Request reliability', link: '/v1/getting-started/request-reliability/' },
+      { label: 'Postman collection', link: '/v1/resources/code-examples/#postman' },
+    ],
+  },
+  {
+    label: 'Guides',
+    items: [
+      { label: 'Account setup', link: '/v1/guides/account-setup/' },
+      { label: 'Financial controls', link: '/v1/guides/account-lifecycle/' },
+      { label: 'Adjustments', link: '/v1/guides/financial-adjustments/' },
+      { label: 'Configuration', link: '/v1/guides/configuration/' },
+      { label: 'Payment jobs', link: '/v1/guides/payment-jobs/' },
+      { label: 'Legacy batches', link: '/v1/guides/legacy-batches/' },
+    ],
+  },
+  {
+    label: 'Concepts',
+    items: [
+      { label: 'Tenant isolation', link: '/v1/concepts/tenant-isolation/' },
+      { label: 'Idempotency and retries', link: '/v1/concepts/idempotency/' },
+      { label: 'Errors', link: '/v1/concepts/errors/' },
+      { label: 'Projections', link: '/v1/concepts/projections/' },
+    ],
+  },
+  {
+    label: 'Reference',
+    items: [
+      { label: 'Identity Access API', link: '/v1/api/identity-access/' },
+      { label: 'Ledger Core API', link: '/v1/api/ledger-core/' },
+      { label: 'Workbench API', link: '/v1/api/workbench/' },
+      { label: 'Current limitations', link: '/v1/resources/limitations/' },
+    ],
+  },
+  {
+    label: 'Resources',
+    items: [
+      { label: 'Code examples', link: '/v1/resources/code-examples/' },
+      { label: 'GitHub', link: 'https://github.com/mavulahq' },
+      { label: 'Support', link: 'https://github.com/orgs/mavulahq/discussions' },
+    ],
+  },
+];
+
+export default defineConfig({
+  site: 'https://mavulahq.github.io',
+  base: '/developer-docs',
+  integrations: [
+    starlight({
+      title: 'MAVULA Developer Docs',
+      description: 'Integration guides and public API reference for MAVULA financial infrastructure.',
+      customCss: ['./src/styles/custom.css'],
+      favicon: '/favicon.svg',
+      social: [
+        { icon: 'github', label: 'GitHub', href: 'https://github.com/mavulahq/developer-docs' },
+      ],
+      sidebar,
+      pagination: true,
+      lastUpdated: true,
+      editLink: {
+        baseUrl: 'https://github.com/mavulahq/developer-docs/edit/main/',
+      },
+      head: [
+        { tag: 'meta', attrs: { name: 'theme-color', content: '#071a45' } },
+        { tag: 'meta', attrs: { property: 'og:site_name', content: 'MAVULA Developer Docs' } },
+      ],
+    }),
+  ],
+});

examples/postman/MAVULA-API-v1.postman_collection.json

@@ -0,0 +1,76 @@
+{
+  "info": {
+    "name": "MAVULA API v1",
+    "description": "Public identity, ledger and workbench integration workflows.",
+    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
+  },
+  "variable": [
+    { "key": "identity_base_url", "value": "https://identity.mavula.io" },
+    { "key": "ledger_base_url", "value": "https://ledger.mavula.io" },
+    { "key": "workbench_base_url", "value": "https://workbench.mavula.io" },
+    { "key": "access_token", "value": "" },
+    { "key": "account_id", "value": "" },
+    { "key": "request_id", "value": "" }
+  ],
+  "item": [
+    {
+      "name": "Identity",
+      "item": [
+        {
+          "name": "Effective identity",
+          "request": {
+            "method": "GET",
+            "header": [{ "key": "Authorization", "value": "Bearer {{access_token}}" }],
+            "url": "{{identity_base_url}}/api/v1/me"
+          }
+        }
+      ]
+    },
+    {
+      "name": "Accounts",
+      "item": [
+        {
+          "name": "Create account",
+          "request": {
+            "method": "POST",
+            "header": [
+              { "key": "Authorization", "value": "Bearer {{access_token}}" },
+              { "key": "Content-Type", "value": "application/json" },
+              { "key": "Idempotency-Key", "value": "{{$guid}}" },
+              { "key": "X-Correlation-ID", "value": "{{$guid}}" }
+            ],
+            "body": { "mode": "raw", "raw": "{\n  \"customer_id\": \"customer_001\",\n  \"product_id\": \"current_account_mzn\",\n  \"name\": \"Operating account\",\n  \"currency\": \"MZN\"\n}" },
+            "url": "{{ledger_base_url}}/api/accounts"
+          }
+        },
+        {
+          "name": "Submit freeze request",
+          "request": {
+            "method": "POST",
+            "header": [
+              { "key": "Authorization", "value": "Bearer {{access_token}}" },
+              { "key": "Content-Type", "value": "application/json" },
+              { "key": "Idempotency-Key", "value": "{{$guid}}" },
+              { "key": "X-Correlation-ID", "value": "{{$guid}}" }
+            ],
+            "body": { "mode": "raw", "raw": "{\n  \"transition\": \"FREEZE\",\n  \"reason\": \"Suspected fraud\"\n}" },
+            "url": "{{ledger_base_url}}/api/accounts/{{account_id}}/status-transitions"
+          }
+        }
+      ]
+    },
+    {
+      "name": "Workbench",
+      "item": [
+        {
+          "name": "Read platform status",
+          "request": {
+            "method": "GET",
+            "header": [{ "key": "Authorization", "value": "Bearer {{access_token}}" }],
+            "url": "{{workbench_base_url}}/api/status"
+          }
+        }
+      ]
+    }
+  ]
+}