RFC-0002: publish versioned public API reference

.github/workflows/pages.yml

@@ -1,5 +1,6 @@
 name: Publish API Reference
 on:
+  push: { branches: [main] }
   workflow_dispatch: {}
 permissions:
   contents: read
@@ -12,8 +13,17 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
+      - uses: pnpm/action-setup@v6
+        with: { version: 10.33.0 }
+      - uses: actions/setup-node@v6
+        with: { node-version: 22.22.3, cache: pnpm }
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm guardian:check
+      - run: pnpm contracts:check
+      - run: pnpm test
+      - run: pnpm build
       - uses: actions/upload-pages-artifact@v4
-        with: { path: .github/pages-bootstrap }
+        with: { path: dist }
   deploy:
     if: github.ref == 'refs/heads/main'
     permissions:

.github/workflows/required-ci.yml

@@ -8,6 +8,12 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
+      - uses: pnpm/action-setup@v6
+        with: { version: 10.33.0 }
       - uses: actions/setup-node@v6
-        with: { node-version: 22.22.3 }
-      - run: node scripts/guardian.mjs
+        with: { node-version: 22.22.3, cache: pnpm }
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm guardian:check
+      - run: pnpm contracts:check
+      - run: pnpm test
+      - run: pnpm build

.gitignore

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

README.md

@@ -1,11 +1,37 @@
-# 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 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
+
+- `identity-access.public.v1.yaml`
+- `ledger-core.public.v1.yaml`
+- `workbench.public.v1.yaml`
+
+`sources.lock.json` binds each published copy to its owner repository and
+SHA-256 digest. `pnpm contracts:check` rejects drift and internal routes.
+
+## Validation
+
+```bash
+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.dev" },
+    { "key": "ledger_base_url", "value": "https://ledger.mavula.dev" },
+    { "key": "workbench_base_url", "value": "https://workbench.mavula.dev" },
+    { "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"
+          }
+        }
+      ]
+    }
+  ]
+}