feat(harbour): schema-first Gaia-X Loire compliance, delegated signing, did:ethr

.github/copilot-instructions.md

@@ -7,37 +7,38 @@ This repository contains cryptographic libraries for signing and verifying verif
 ```bash
 # Install dev dependencies
 make setup
-make install-dev
+make install dev
 
 # Run all tests (Python + TypeScript)
-make test-all
+make test full
 
 # Run Python tests only
 make test
 
 # Run TypeScript tests only
-make test-ts
+make test ts
 
 # Build TypeScript
-make build-ts
+make build
 
 # Lint and format
 make lint
 make format
 
 # Run with coverage
-make test-cov
+make test cov
 ```
 
 ## Instruction Files
 
 Read these BEFORE making changes:
 
-| Topic              | File                   |
-| ------------------ | ---------------------- |
-| Agent instructions | [../AGENTS.md](../AGENTS.md) |
-| Claude guidance    | [../CLAUDE.md](../CLAUDE.md) |
-| Documentation      | [../README.md](../README.md) |
+| Topic              | File                                      |
+| ------------------ | ----------------------------------------- |
+| Agent instructions | [AGENTS.md](../AGENTS.md)                 |
+| Claude guidance    | [CLAUDE.md](../CLAUDE.md)                 |
+| Documentation      | [README.md](../README.md)                 |
+| Architecture       | [architecture.md](../docs/architecture.md)|
 
 ## Core Principles
 
@@ -47,7 +48,7 @@ Read these BEFORE making changes:
 
 ## Project Structure
 
-```
+```text
 src/
 ├── python/
 │   ├── harbour/        # Crypto library (keys, sign, verify, sd-jwt, kb-jwt, x509)
@@ -102,15 +103,20 @@ git commit -s -S -m "feat(harbour): add KB-JWT support"
 
 ## Preparing Commits and Pull Requests
 
-When instructed to prepare a commit or PR, **do not commit directly**. Instead:
+When instructed to prepare a commit or PR, default to preparing the `.playground`
+files first. After **explicit human confirmation in the current session**, the
+agent may directly create the signed commit, push the branch, and open the PR
+using the prepared `.playground` content. Otherwise:
 
 1. Create files in the `.playground/` directory (already in `.gitignore`)
 2. Generate two markdown files:
    - `.playground/commit-message.md` — Conventional commit message(s)
    - `.playground/pr-description.md` — PR description
 
 The human operator will review these files and either:
-- Use them to manually commit/push and create a PR, or
+
+- Use them to manually commit/push and create a PR,
+- Ask the agent to perform the signed commit/push/PR flow directly after explicit confirmation, or
 - Use automated tooling with signed commits (`git commit -s -S`)
 
 ## Common Mistakes to Avoid
@@ -119,4 +125,4 @@ The human operator will review these files and either:
 - ❌ **Don't forget CLI** — All Python modules need `main()` with `--help`
 - ❌ **Don't break parity** — Keep Python and TypeScript APIs consistent
 - ❌ **Don't commit without signing** — Always use `-s -S`
-- ❌ **Don't skip tests** — Run `make test-all` before committing
+- ❌ **Don't skip tests** — Run `make test full` before committing

.github/workflows/cd-release.yml

@@ -4,11 +4,12 @@ on:
   push:
     tags:
       - 'v*.*.*'
+      - 'v*.*.*-rc.*'
 
   workflow_dispatch:
     inputs:
       tag:
-        description: 'Release tag (e.g., v0.1.0)'
+        description: 'Release tag (e.g., v1.0.0 or v1.0.0-rc.1)'
         required: true
         type: string
 
@@ -64,17 +65,76 @@ jobs:
           name: Release ${{ steps.tag.outputs.tag }}
           body: ${{ steps.changelog.outputs.content }}
           draft: false
-          prerelease: false
+          prerelease: ${{ contains(steps.tag.outputs.tag, '-rc.') }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
-  docs:
-    name: 📚 Publish Documentation
+  publish:
+    name: 📦 Publish Artifacts & Docs
     needs: release
-    uses: ./.github/workflows/cd-docs.yml
-    with:
-      ref: main
+    runs-on: ubuntu-latest
     permissions:
       contents: read
       pages: write
       id-token: write
+    concurrency:
+      group: "pages"
+      cancel-in-progress: false
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          submodules: recursive
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: 'pip'
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
+      - name: Enable Corepack
+        run: corepack enable
+
+      - name: Install Python dependencies
+        run: python3 -m pip install -e ".[dev,docs]"
+
+      - name: Install TypeScript dependencies
+        working-directory: src/typescript/harbour
+        run: yarn install --immutable
+
+      - name: Generate artifacts
+        run: make generate
+
+      - name: Validate artifacts
+        run: make validate shacl
+
+      - name: Generate TypeScript API docs
+        working-directory: src/typescript/harbour
+        run: npx typedoc --out ../../../docs/api/typescript index.ts --skipErrorChecking
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+
+      - name: Build MkDocs site
+        run: mkdocs build --strict --site-dir site
+
+      - name: Prepare w3id artifacts
+        run: make release-artifacts
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./site
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/ci.yml

@@ -24,13 +24,13 @@ jobs:
           cache: 'pip'
 
       - name: Install dependencies
-        run: python3 -m pip install -e ".[dev]"
+        run: make install dev
 
       - name: Run pre-commit
-        run: pre-commit run --all-files
+        run: make lint
 
-  lint-ts:
-    name: Lint (TypeScript)
+  lint-markdown:
+    name: Lint (Markdown)
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -39,20 +39,29 @@ jobs:
         with:
           node-version: "22"
 
-      - name: Enable Corepack
-        run: corepack enable
+      - name: Lint Markdown
+        run: npx --yes markdownlint-cli2
 
-      - name: Install dependencies
-        working-directory: src/typescript/harbour
-        run: yarn install --immutable
+  lint-ts:
+    name: Lint (TypeScript)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
 
-      - name: Type check
-        working-directory: src/typescript/harbour
-        run: yarn lint
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
+      - name: Lint TypeScript
+        run: make lint ts
 
   generate-validate:
-    name: Generate & Validate
-    runs-on: ubuntu-latest
+    name: Generate & Validate (${{ matrix.os }})
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v4
         with:
@@ -63,10 +72,10 @@ jobs:
           python-version: "3.12"
           cache: 'pip'
 
-      - name: Install dependencies
+      - name: Install dependencies and submodules
         run: |
-          python3 -m pip install -e ".[dev]" linkml
-          python3 -m pip install -e "./submodules/ontology-management-base"
+          make install dev
+          make setup submodules
 
       - name: Generate artifacts
         run: make generate
@@ -75,49 +84,54 @@ jobs:
         run: make validate
 
       - name: Validate examples (SHACL conformance)
-        run: make validate-shacl
+        run: make validate shacl
 
   test-python:
-    name: Test (Python)
-    runs-on: ubuntu-latest
+    name: Test (Python) (${{ matrix.os }}, py${{ matrix.python-version }})
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.12", "3.13"]
+    runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v4
 
       - uses: actions/setup-python@v5
         with:
-          python-version: "3.12"
+          python-version: ${{ matrix.python-version }}
           cache: 'pip'
 
       - name: Install dependencies
-        run: python3 -m pip install -e ".[dev]"
+        run: make install dev
 
       - name: Run tests
-        run: PYTHONPATH=src/python:$PYTHONPATH pytest tests/ -v --tb=short --cov
+        run: make test
 
   test-ts:
-    name: Test (TypeScript)
-    runs-on: ubuntu-latest
+    name: Test (TypeScript) (${{ matrix.os }})
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v4
 
       - uses: actions/setup-node@v4
         with:
           node-version: "22"
 
-      - name: Enable Corepack
-        run: corepack enable
-
-      - name: Install dependencies
-        working-directory: src/typescript/harbour
-        run: yarn install --immutable
-
       - name: Run tests
-        working-directory: src/typescript/harbour
-        run: yarn test
+        run: make test ts
 
   test-interop:
-    name: Cross-Runtime Interop
-    runs-on: ubuntu-latest
+    name: Cross-Runtime Interop (${{ matrix.os }})
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
     needs: [test-python, test-ts]
     steps:
       - uses: actions/checkout@v4
@@ -131,15 +145,38 @@ jobs:
         with:
           node-version: "22"
 
-      - name: Enable Corepack
-        run: corepack enable
-
       - name: Install Python dependencies
-        run: python3 -m pip install -e ".[dev]"
+        run: make install dev
 
-      - name: Install TypeScript dependencies
-        working-directory: src/typescript/harbour
-        run: yarn install --immutable
+      - name: Build TypeScript
+        run: make build ts
 
       - name: Run interop tests
-        run: PYTHONPATH=src/python:$PYTHONPATH pytest tests/interop/test_cross_runtime.py -v --tb=short
+        run: make test interop
+
+  # --- Credential Lifecycle Story ---
+  story:
+    name: Credential Story (${{ matrix.os }})
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    needs: [generate-validate]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: 'pip'
+
+      - name: Install dependencies and submodules
+        run: |
+          make install dev
+          make setup submodules
+
+      - name: Run credential storyline (generate → sign → verify → SHACL validate)
+        run: make story