fix(ci): resolve CI failures, fix broken links, add Vale and Prettier to pre-commit

CI workflow fixes:
- Update lychee-action to v2.8.0 and markdownlint-cli2-action to v23.0.0
- Add .lycheeignore for forward refs, placeholder URLs, and flaky sites

Pre-commit improvements:
- Replace mirrors-prettier with local npx prettier --check hook
  (matches CI version, avoids creating unstaged files)
- Add Vale hook (errata-ai/vale v3.9.6) to catch prose lint locally

Vale configuration (.vale.ini):
- Disable rules incompatible with technical specification prose:
  Passive voice, E-Prime, TooWordy, Headings, Contractions,
  Parens, Semicolons, Quotes, EmDash, Spacing, Exclamation,
  Annotations, Typography
- Add e.V. to vocabulary accept list

Cross-spec prose lint fixes:
- Replace all "e.g." with "for example" across all EVES specs
- Replace all "i.e." with "that is" across all EVES specs
- Fix "specifications specifications" typo in EVES/README.md

Broken link fixes (EVES-003):
- Pinata docs: /web3/pinning → /api-reference/endpoint/ipfs
- Ontology repos: GAIA-X4PLC-AAD → ASCS-eV/artifacts (gx, tzip21)
- SPDX ref: StackExchange answer → spdx.org/licenses
- GitLab TZIP: gitlab.com/tzip → gitlab.com/tezos
- Tezos research: research.tezos.com → docs.tezos.com
- Remove duplicate reference entries, add missing bullets

Add CLAUDE.md with project setup and quality check instructions.

Signed-off-by: jdsika <carlo.van-driesten@vdl.digital>

Author: jdsika

.github/styles/Vocab/EVES/accept.txt

@@ -29,3 +29,4 @@ DPoP
 SPARQL
 SSI
 Catena-X
+e\.V\.

.github/workflows/link_checker.yml

@@ -14,17 +14,17 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Restore lychee cache
-        uses: actions/cache@1bd1e32a3bdc45362d1e726936510720a7c30a57 # v4.2.0
+        uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4
         with:
           path: .lycheecache
           key: lychee-cache-${{ github.sha }}
           restore-keys: lychee-cache-
 
       - name: Check links
-        uses: lycheeverse/lychee-action@f81112d0d2814ded911bd23e3beaa9dda9f8ca55 # v2.3.0
+        uses: lycheeverse/lychee-action@8646ba30535128ac92d33dfc9133794bfdd9b411 # v2.8.0
         with:
           args: >-
             --cache

.github/workflows/markdown_linter.yml

@@ -12,10 +12,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Run markdownlint
-        uses: DavidAnson/markdownlint-cli2-action@db4f21d957a58a0515c3e6b0fb16b2a13e97a1e6 # v19.1.0
+        uses: DavidAnson/markdownlint-cli2-action@ce4853d43830c74c1753b39f3cf40f71c2031eb9 # v23.0.0
         with:
           config: .markdownlint.json
           globs: "**/*.md"

.lycheeignore

@@ -0,0 +1,13 @@
+# Forward references to EVES specs not yet written
+EVES-009/eves-009.md
+
+# Placeholder/example URLs used in spec text (not real endpoints)
+https://assets.envited-x.net/
+https://metadata.envited-x.net/
+https://ipfs.envited-x.net/
+
+# GitLab blocks automated requests with 403
+https://gitlab.com/tezos/tzip/
+
+# Flaky external sites (intermittent connection resets in CI)
+https://www.conventionalcommits.org/

.pre-commit-config.yaml

@@ -15,9 +15,16 @@ repos:
       - id: markdownlint
         args: ["--config", ".markdownlint.json"]
 
-  - repo: https://github.com/pre-commit/mirrors-prettier
-    rev: v4.0.0-alpha.8
+  - repo: local
     hooks:
       - id: prettier
+        name: prettier
+        entry: npx prettier --check --ignore-path .prettierignore
+        language: system
         types_or: [markdown, json, yaml]
-        args: ["--prose-wrap", "preserve"]
+
+  - repo: https://github.com/errata-ai/vale
+    rev: v3.9.6
+    hooks:
+      - id: vale
+        types: [markdown]

.vale.ini

@@ -10,3 +10,30 @@ BasedOnStyles = Vale, Google, proselint, write-good
 Google.Acronyms = NO
 Google.We = NO
 Vale.Spelling = NO
+# EVES specs quote field names like "name", "tags" — comma placement doesn't apply
+Google.Quotes = NO
+# NOTE/TODO in blockquotes is standard RFC/spec style
+proselint.Annotations = NO
+# EVES uses spaced em-dashes (` — `) consistently
+Google.EmDash = NO
+# Filenames contain "..." which is not prose typography
+proselint.Typography = NO
+# "e.V." is the German legal abbreviation (eingetragener Verein)
+Google.Spacing = NO
+# Occasional emphasis is acceptable in specs
+Google.Exclamation = NO
+# Passive voice is standard in normative specifications ("MUST be derived from...")
+write-good.Passive = NO
+Google.Passive = NO
+# E-Prime ("avoid is/are/was") is incompatible with specification language
+write-good.E-Prime = NO
+# "however", "indicate", "requirement" are normal technical terms
+write-good.TooWordy = NO
+# Specs use title-case section headings (e.g. "Backwards Compatibility")
+Google.Headings = NO
+# Specs MUST NOT use contractions per formal writing conventions
+Google.Contractions = NO
+# Parenthetical clarifications are common in specs
+Google.Parens = NO
+# Semicolons are appropriate in complex specification sentences
+Google.Semicolons = NO

CLAUDE.md

@@ -0,0 +1,63 @@
+# CLAUDE.md
+
+## Project overview
+
+EVES (ENVITED-X Verifiable Ecosystem Specifications) defines standards for the ENVITED-X Data Space.
+Each specification lives in `EVES/EVES-NNN/eves-nnn.md` with associated examples, schemas, and assets.
+
+## Setup
+
+```sh
+npm install
+pre-commit install
+```
+
+## Quality checks
+
+Before every commit, run:
+
+```sh
+make lint          # markdownlint + frontmatter validation
+make format-check  # Prettier formatting
+```
+
+Pre-commit hooks enforce: trailing whitespace, end-of-file newlines, valid YAML/JSON, no merge conflicts, markdownlint, Prettier formatting (check mode), and Vale prose linting.
+
+If Prettier fails, run `npx prettier --write .` to auto-format, then re-stage and commit.
+
+CI additionally runs link checking (`link_checker.yml`).
+
+### Vale prose lint rules
+
+The project uses Vale with Google, proselint, and write-good styles (see `.vale.ini`).
+Several rules are disabled because they conflict with technical specification conventions (see comments in `.vale.ini`).
+
+Key active rule that causes CI failures:
+
+- Use "for example" instead of "e.g." or "i.e." (`Google.Latin`)
+
+To run Vale locally: install [Vale](https://vale.sh/docs/install), then `vale sync && vale EVES/`.
+
+### Markdown lint rules
+
+See `.markdownlint.json`. Maximum line length is 300 characters (tables and code blocks are exempt).
+HTML elements `<a>`, `<br>`, `<img>`, `<sup>` are allowed.
+
+## File conventions
+
+- Specification documents use YAML frontmatter with fields: `eves-identifier`, `title`, `author`, `status`, `type`, `created`, `requires`, `replaces`
+- JSON schemas go in `eves-nnn-schemas/` directories (excluded from Prettier in `.prettierignore`)
+- Example files go in `example/` directories (excluded from Prettier in `.prettierignore`)
+- Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/) with scope: `feat(EVES-003): ...`, `fix(ci): ...`
+- Branches follow `feat/eves-nnn-description` naming
+
+## Ontology references
+
+The ENVITED-X ontologies are maintained in [ontology-management-base](https://github.com/ASCS-eV/ontology-management-base).
+Current versions: `envited-x/v3/`, `manifest/v5/`, `hdmap/v6/`.
+
+The Gaia-X ontology follows the Loire (25.11) release. Key naming:
+
+- `envited-x:ResourceDescription` (subclass of `gx:VirtualResource`) carries the GX compliance metadata
+- `gx:name`, `gx:description` are used in the `envited-x:ResourceDescriptionShape` SHACL
+- `gx:license`, `gx:copyrightOwnedBy`, `gx:resourcePolicy` remain GX-native properties

EVES/EVES-001/eves-001.md

@@ -64,7 +64,7 @@ Each EVES must pass through the following stages:
    - **Future Changes**: Only changes designated as a minor editorial update by Editors are allowed in this stage.
 
 5. **Deferred/Rejected**
-   - **Deferred**: The EVES is paused for future discussion (e.g., lack of resources, overshadowed by another proposal).
+   - **Deferred**: The EVES is paused for future discussion (for example, lack of resources, overshadowed by another proposal).
    - **Rejected**: Consensus cannot be reached, or the specification is fundamentally misaligned with ENVITED-X goals.
 
 6. **Superseded**
@@ -85,20 +85,20 @@ Each EVES must pass through the following stages:
 ### 2. EVES Numbering
 
 - EVES documents follow sequential numbering, starting from EVES-001, EVES-002, and so on.
-- Numbers must be unique and stable once assigned (i.e., no recycling of identifiers).
+- Numbers must be unique and stable once assigned (that is, no recycling of identifiers).
 
 ### 3. EVES Types
 
 Each EVES must declare one of the following **type** fields in its YAML header:
 
 1. **Standards**
-   - Defines technical specifications or protocols recommended for ecosystem adoption (e.g., data formats, APIs).
+   - Defines technical specifications or protocols recommended for ecosystem adoption (for example, data formats, APIs).
 
 2. **Informational**
    - Provides context, best practices, or reference material without strict normative requirements.
 
 3. **Process**
-   - Outlines procedural or governance rules applicable to the ENVITED community (e.g., this EVES-001).
+   - Outlines procedural or governance rules applicable to the ENVITED community (for example, this EVES-001).
 
 ### 4. Roles and Responsibilities
 
@@ -121,7 +121,7 @@ Each EVES must declare one of the following **type** fields in its YAML header:
 
 - A subset of EVES Editors with voting rights as full ASCS e.V. ENVITED members.
 - Provide the final decision on moving an EVES from Candidate to Final.
-- Must meet quorum requirements (e.g., at least two Approvers) to grant or deny Final status.
+- Must meet quorum requirements (for example, at least two Approvers) to grant or deny Final status.
 
 ### 4.5 Conflict Resolution
 

EVES/EVES-002/eves-002.md

@@ -36,10 +36,10 @@ The ENVITED-X Data Space is built on the following core modules:
 
 - **Purpose**:
   - Establish trust by verifying user and organization identities.
-  - Enable permission management (e.g., membership validation, terms of service acceptance).
+  - Enable permission management (for example, membership validation, terms of service acceptance).
 - **Key Features**:
   - Credentials are issued via [SimpulseID](https://identity.ascs.digital) and stored in W3C-compliant wallets like [Altme](https://altme.io).
-  - Future support for contract-based credentials (e.g., purchase or download permissions).
+  - Future support for contract-based credentials (for example, purchase or download permissions).
 - **Standards**:
   - Gaia-X Trust Framework.
   - W3C Verifiable Credentials and DIDs.
@@ -52,7 +52,7 @@ The ENVITED-X Data Space is built on the following core modules:
   - Enable real-time credential checks during system interactions.
 - **Functionality**:
   - Tracks the **uuid** of credentials to ensure privacy.
-  - Manages credential statuses (e.g., active/inactive for revocation).
+  - Manages credential statuses (for example, active/inactive for revocation).
 - **Use Cases**:
   - Credential validation during login.
   - Whitelisting users for minting and accessing assets.
@@ -99,11 +99,11 @@ The interaction between modules can be summarized as follows:
 1. **Credential Issuance**:
    - A user or organization requests a credential via SimpulseID following the process in EVES-008.
    - Credential metadata includes identity, permissions, and additional attributes.
-   - Credential is stored in a wallet (e.g., Altme) and referenced by uuid in the registry contract.
+   - Credential is stored in a wallet (for example, Altme) and referenced by uuid in the registry contract.
 
 2. **Login and Validation**:
    - User logs in to ENVITED-X.
-   - The system validates the credential (e.g., membership status) via the registry contract.
+   - The system validates the credential (for example, membership status) via the registry contract.
 
 3. **Asset Registration**:
    - User uploads simulation assets to ENVITED-X following the process in EVES-003.
@@ -142,7 +142,7 @@ Future EVES will provide detailed specifications for each module.
 
 1. [SimpulseID](https://identity.ascs.digital)
 2. [Altme Wallet](https://altme.io)
-3. [Tezos FA2.1 Standard](https://gitlab.com/tzip/tzip/-/blob/master/proposals/tzip-21/tzip-21.md)
+3. [Tezos FA2.1 Standard](https://gitlab.com/tezos/tzip/-/blob/master/proposals/tzip-21/tzip-21.md)
 4. [Etherlink Bridge](https://www.etherlinkbridge.com/bridge)
 5. [EVES-003: ENVITED Asset Definition and Upload Process](../EVES-003/eves-003.md)
 6. [Gaia-X Trust Framework](https://docs.gaia-x.eu/policy-rules-committee/compliance-document/24.11/)

EVES/EVES-003/eves-003.md

@@ -31,7 +31,7 @@ This EVES addresses the need for clear guidelines to onboard assets and synchron
 
 The `envited-x:SimulationAsset` defines a digital asset within the domain of simulation including the core simulation data and all necessary files for describing, evaluating, and visualizing the dataset.
 All simulation assets MUST be derived from a common `envited-x` ontology defined in the [Gaia-X 4 PLC-AAD Ontology Management Base][1].
-A data space portal SHALL display the currently supported version of the ontologies like e.g.: `https://ontologies.envited-x.net/envited-x/v2/ontology#`.
+A data space portal SHALL display the currently supported version of the ontologies such as: `https://ontologies.envited-x.net/envited-x/v2/ontology#`.
 Each simulation asset SHALL be compliant with the [Gaia-X Ontology and SHACL shapes 2210][2].
 The `gx` turtle shacle shapes are derived from the [Gaia-X Trust Framework Schema][3] and the respective application/ld+json [Gaia-X Trust Framework Shapes][4].
 A [GaiaX Compliant Claims Example][5] MAY be generated using the [GaiaX 4 PLC-AAD Claim Compliance Provider][6].
@@ -54,15 +54,15 @@ Tooling such as the [ENVITED-X Simulation Asset Tools][20] MAY automate the crea
 
 Every `asset.zip` MUST contain the following top-level folders mapped to `envited-x` artifact categories:
 
-| Folder                | `envited-x` Category           | Required    | `envited-x` Access Role | Description                                     |
-| --------------------- | ------------------------------ | ----------- | ----------------------- | ----------------------------------------------- |
-| `simulation-data/`    | `envited-x:isSimulationData`   | MUST        | `envited-x:isOwner`     | Core simulation data (e.g., `.xodr`, `.xosc`)   |
-| `documentation/`      | `envited-x:isDocumentation`    | MUST        | `envited-x:isPublic`    | Documentation files (e.g., `.pdf`, `.txt`)      |
-| `metadata/`           | `envited-x:isMetadata`         | MUST        | `envited-x:isPublic`    | Domain metadata (e.g., `hdmap_instance.json`)   |
-| `media/`              | `envited-x:isMedia`            | MUST        | `envited-x:isPublic`    | Visualizations, images, GeoJSON, 3D previews    |
-| `validation-reports/` | `envited-x:isValidationReport` | RECOMMENDED | `envited-x:isPublic`    | Quality checker reports (e.g., `.xqar`, `.txt`) |
-| _(root)_              | `envited-x:isLicense`          | MUST        | `envited-x:isPublic`    | LICENSE file at the asset root                  |
-| _(root)_              | `envited-x:isManifest`         | MUST        | `envited-x:isPublic`    | `manifest_reference.json` at the asset root     |
+| Folder                | `envited-x` Category           | Required    | `envited-x` Access Role | Description                                            |
+| --------------------- | ------------------------------ | ----------- | ----------------------- | ------------------------------------------------------ |
+| `simulation-data/`    | `envited-x:isSimulationData`   | MUST        | `envited-x:isOwner`     | Core simulation data (for example, `.xodr`, `.xosc`)   |
+| `documentation/`      | `envited-x:isDocumentation`    | MUST        | `envited-x:isPublic`    | Documentation files (for example, `.pdf`, `.txt`)      |
+| `metadata/`           | `envited-x:isMetadata`         | MUST        | `envited-x:isPublic`    | Domain metadata (for example, `hdmap_instance.json`)   |
+| `media/`              | `envited-x:isMedia`            | MUST        | `envited-x:isPublic`    | Visualizations, images, GeoJSON, 3D previews           |
+| `validation-reports/` | `envited-x:isValidationReport` | RECOMMENDED | `envited-x:isPublic`    | Quality checker reports (for example, `.xqar`, `.txt`) |
+| _(root)_              | `envited-x:isLicense`          | MUST        | `envited-x:isPublic`    | LICENSE file at the asset root                         |
+| _(root)_              | `envited-x:isManifest`         | MUST        | `envited-x:isPublic`    | `manifest_reference.json` at the asset root            |
 
 > **Note:** The `envited-x` categories and access roles are formally defined in the [ENVITED-X Ontology][21] which extends the generic [Manifest Ontology][22].
 > The `envited-x:ExtendedLinkShape` constrains the allowed values for both `manifest:hasCategory` and `manifest:hasAccessRole`.
@@ -146,12 +146,12 @@ IPFS is a peer-to-peer content delivery network built around the innovation of c
 
 #### CID v1
 
-Artifacts uploaded to IPFS e.g. using services like [Pinata][9] MUST use the content identifier version [CID v1][11].  
+Artifacts uploaded to IPFS, for example using services like [Pinata][9] MUST use the content identifier version [CID v1][11].  
 In Pinata this is achievable through the API using the `pinataOptions` parameter, as outlined in the [documentation][10].
 
 #### File Naming
 
-Uploaded file names MUST exclude extensions (e.g., use `file` instead of `file.json`) to avoid issues such as double extensions during downloads (e.g., `file.json.json`).
+Uploaded file names MUST exclude extensions (for example, use `file` instead of `file.json`) to avoid issues such as double extensions during downloads (for example, `file.json.json`).
 
 ### 3. Privacy Layer
 
@@ -294,46 +294,47 @@ The compatibility with the current release of the [Gaia-X Policy Rules Complianc
 
 ## References
 
-- [Gaia-X 4 PLC-AAD Ontology Management Base][1]
-- [Gaia-X Ontology and SHACL shapes 2210][2]
+- [ASCS Ontology Management Base][1]
+- [Gaia-X Ontology and SHACL shapes][2]
 - [Gaia-X Trust Framework Schema][3]
 - [Gaia-X Trust Framework Shapes][4]
 - [GaiaX Compliant Claims Example][5]
-- [GaiaX 4 PLC-AAD Claim Compliance Provider][6]
+- [GaiaX Claim Compliance Provider][6]
 - [ASCS HD-Map Asset Example][7]
 - [IPFS][8]
-- [Pinata Documentation][10]
+- [Pinata][9]
+- [Pinata API Documentation][10]
+- [CID v1 Content Addressing][11]
 - [ENVITED-X Data Space Portal][12]
 - [EIP-712][13]
+- [SPDX License List][15]
 - [RFC 2119: Key Words for Use in RFCs to Indicate Requirement Levels][16]
 - [Gaia-X Policy Rules Compliance Document (Release 24.11)][17]
 - [Marketplace Contract Reference Implementation][18]
-- [ENVITED-X Simulation Asset Tools][20]
-- [ENVITED-X Ontology][21]
-- [Manifest Ontology][22]
+- [TZIP-21 Ontology][19]
 - [ENVITED-X Simulation Asset Tools][20]
 - [ENVITED-X Ontology][21]
 - [Manifest Ontology][22]
 
 [1]: https://github.com/ASCS-eV/ontology-management-base/
-[2]: https://github.com/GAIA-X4PLC-AAD/ontology-management-base/tree/main/gx
+[2]: https://github.com/ASCS-eV/ontology-management-base/tree/main/artifacts/gx
 [3]: https://registry.lab.gaia-x.eu/v1/api/trusted-schemas-registry/v2/schemas/gax-trust-framework
 [4]: https://registry.lab.gaia-x.eu/v1/api/trusted-shape-registry/v1/shapes/jsonld/trustframework#
 [5]: https://github.com/GAIA-X4PLC-AAD/gaia-x-compliant-claims-example
 [6]: https://github.com/GAIA-X4PLC-AAD/claim-compliance-provider
 [7]: https://github.com/ASCS-eV/hd-map-asset-example/releases/tag/v0.2.3
 [8]: https://ipfs.tech/
 [9]: https://pinata.cloud/
-[10]: https://docs.pinata.cloud/web3/pinning/pinata-metadata#pinataoptions
+[10]: https://docs.pinata.cloud/api-reference/endpoint/ipfs/pin-file-to-ipfs
 [11]: https://docs.ipfs.tech/concepts/content-addressing/#version-1-v1
 [12]: https://envited-x.net/
 [13]: https://eips.ethereum.org/EIPS/eip-712
 [14]: https://json-schema.org/understanding-json-schema/reference/string#dates-and-times
-[15]: https://softwareengineering.stackexchange.com/a/450839/443441
+[15]: https://spdx.org/licenses/
 [16]: https://datatracker.ietf.org/doc/html/rfc2119
 [17]: https://docs.gaia-x.eu/policy-rules-committee/compliance-document/24.11/
 [18]: https://github.com/ASCS-eV/smart-contracts/tree/main/contracts/marketplace/
-[19]: https://github.com/GAIA-X4PLC-AAD/ontology-management-base/tree/main/tzip21
+[19]: https://github.com/ASCS-eV/ontology-management-base/tree/main/artifacts/tzip21
 [20]: https://github.com/openMSL/sl-5-8-asset-tools
 [21]: https://github.com/ASCS-eV/ontology-management-base/tree/main/artifacts/envited-x
 [22]: https://github.com/ASCS-eV/ontology-management-base/tree/main/artifacts/manifest