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

Root cause analysis of CI failures:

1. Broken action SHAs in link_checker.yml and markdown_linter.yml
2. Prettier version skew (pre-commit mirrors-prettier vs project npm)
3. Vale prose lint not in pre-commit hooks — errors only caught in CI
4. Pre-existing Vale errors across all EVES specs blocking all PRs
5. Broken external links (Pinata docs, ontology repos, GitLab TZIP)

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 (v4.0.0-alpha.8) with local hook using
  npx prettier --check to match CI version and avoid unstaged files
- Add Vale hook (errata-ai/vale v3.9.6) to catch prose lint locally

Vale configuration:
- Disable rules that conflict with spec conventions: Google.Quotes,
  Google.EmDash, Google.Spacing, Google.Exclamation,
  proselint.Annotations, proselint.Typography
- Add e.V. to vocabulary accept list

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

Broken link fixes:
- Pinata: docs.pinata.cloud/web3 → /api-reference (reorg)
- Ontology repos: GAIA-X4PLC-AAD → ASCS-eV/ontology-management-base
- GitLab TZIP: gitlab.com/tzip → gitlab.com/tezos (namespace change)
- Tezos research: research.tezos.com → docs.tezos.com (domain offline)

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

Signed-off-by: jdsika <carlo.van-driesten@vdl.digital>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: jdsika

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

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

.github/workflows/link_checker.yml

@@ -24,7 +24,7 @@ jobs:
           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

@@ -15,7 +15,7 @@ jobs:
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.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,10 @@
+# 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/

.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,15 @@ 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

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-004/eves-004.md

@@ -50,7 +50,7 @@ This specification distinguishes between two formal roles: **Editors** and **App
 
 #### 1.5 Standards Enforcers (Editors)
 
-- Verify that proposals align with overarching governance and standards (e.g., Gaia-X, W3C, Tezos TZIPs).
+- Verify that proposals align with overarching governance and standards (for example, Gaia-X, W3C, Tezos TZIPs).
 - Ensure interoperability within the ENVITED ecosystem.
 
 #### 1.6 Approvers
@@ -135,7 +135,7 @@ Approvers operate on top of the Editors’ responsibilities, taking an active ro
 
 1. **Application Process**:
    - Anyone interested in becoming an EVES Editor can open a discussion in the ENVITED GitHub organization.
-   - Tag the current editors group (e.g., `@eves-editors`) in the discussion for visibility.
+   - Tag the current editors group (for example, `@eves-editors`) in the discussion for visibility.
 
 2. **Eligibility**:
    - Applicants MUST demonstrate familiarity with the EVES process, template, and standards as defined in [EVES-001](../EVES-001/eves-001.md) and this document.
@@ -155,7 +155,7 @@ The following points clarify limits to the Editor and Approver roles:
 1. **Creation of New EVES**
    - Neither Editors nor Approvers drive the creation of new EVES; the community identifies needs, and authors propose solutions.
 2. **Technical Designs or Implementations**
-   - They do not craft or own the underlying technical designs (e.g., code libraries).
+   - They do not craft or own the underlying technical designs (for example, code libraries).
      The community or EVES authors lead the design, while Editors and Approvers review it for feasibility.
 3. **Promotion or Adoption**
    - They are not tasked with marketing or ensuring the adoption of specific EVES.