YNU-864: Add language harness skeleton

.github/workflows/vale.yml

@@ -0,0 +1,37 @@
+name: Vale
+
+on:
+  pull_request:
+    paths:
+      - ".github/workflows/vale.yml"
+      - ".pre-commit-config.yaml"
+      - ".vale.ini"
+      - ".vale/**"
+      - "docs/**/*.md"
+      - "docs/**/*.mdx"
+      - "templates/**/*.md"
+      - "templates/**/*.mdx"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  vale:
+    name: Vale advisory lint
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Run Vale
+        uses: errata-ai/vale-action@v2.1.1
+        with:
+          files: '["docs", "templates"]'
+          fail_on_error: true
+          filter_mode: added
+          vale_flags: "--minAlertLevel=error"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.pre-commit-config.yaml

@@ -0,0 +1,8 @@
+repos:
+  - repo: local
+    hooks:
+      - id: vale-docs
+        name: Vale docs language lint
+        entry: vale --minAlertLevel=error
+        language: system
+        files: ^(docs|templates)/.*\.(md|mdx)$

.vale.ini

@@ -0,0 +1,8 @@
+StylesPath = .vale/styles
+MinAlertLevel = suggestion
+
+[formats]
+mdx = md
+
+[*.{md,mdx}]
+BasedOnStyles = Yellow

.vale/styles/Yellow/AISlop.yml

@@ -0,0 +1,34 @@
+extends: existence
+message: "Avoid '%s'. Use direct, concrete wording."
+level: error
+ignorecase: true
+tokens:
+  - "—"
+  - "–"
+  - "\\bdelve\\b"
+  - "\\bleverage\\b"
+  - "\\bunlock\\b"
+  - "\\bharness(?:es|ed|ing)?\\b"
+  - "\\bseamlessly\\b"
+  - "\\bseamless\\b"
+  - "\\brobust\\b"
+  - "\\bpowerful\\b"
+  - "\\bboasts?\\b"
+  - "\\beffortless\\b"
+  - "\\belevate\\b"
+  - "\\bstreamline\\b"
+  - "\\brevolutionary\\b"
+  - "\\bcutting-edge\\b"
+  - "\\bbleeding-edge\\b"
+  - "\\bin today's\\b"
+  - "\\bit's worth noting\\b"
+  - "\\bit is important to note\\b"
+  - "\\bnavigating the landscape\\b"
+  - "\\bthe world of\\b"
+  - "\\bat the end of the day\\b"
+  - "\\bthat being said\\b"
+  - "\\byou may want to\\b"
+  - "\\byou might consider\\b"
+  - "\\bfeel free to\\b"
+  - "\\bembark on your journey\\b"
+  - "\\bunlock the power of\\b"

.vale/styles/Yellow/BuildPageShape.yml

@@ -0,0 +1,6 @@
+extends: occurrence
+message: "Build how-to pages should include TL;DR, Step-by-step, Verify, and Next steps headings."
+level: warning
+scope: raw
+token: "(?m)^## (TL;DR|Step-by-step|Verify|Next steps)\\b"
+min: 4

.vale/styles/Yellow/CrossLink.yml

@@ -0,0 +1,6 @@
+extends: occurrence
+message: "Learn and Protocol pages should declare their counterpart link in frontmatter."
+level: warning
+scope: raw
+token: "(?m)^(protocol_link|learn_link):"
+min: 1

.vale/styles/Yellow/NeedBasedLabels.yml

@@ -0,0 +1,11 @@
+extends: existence
+message: "Consider a task-based title instead of internal label '%s'."
+level: suggestion
+scope: heading
+ignorecase: true
+tokens:
+  - "\\bwdk-wallet-ton\\b"
+  - "\\bnitronode-rpc-overview\\b"
+  - "\\bsdk-compat-eventpoller\\b"
+  - "\\bapp-sessions-multi-party\\b"
+  - "\\b[a-z0-9]+(?:-[a-z0-9]+){2,}\\b"

.vale/styles/Yellow/NoMetaphor.yml

@@ -0,0 +1,11 @@
+extends: existence
+message: "Avoid analogy or metaphor in reference prose: '%s'."
+level: warning
+ignorecase: true
+tokens:
+  - "\\blike a\\b"
+  - "\\blike an\\b"
+  - "\\bas if\\b"
+  - "\\bthink of\\b"
+  - "\\banalogy\\b"
+  - "\\bmetaphor\\b"

.vale/styles/Yellow/NoNarrative.yml

@@ -0,0 +1,6 @@
+extends: occurrence
+message: "Reference prose should stay terse. Split long paragraphs before they become narrative."
+level: warning
+scope: paragraph
+token: "\\b\\w+\\b"
+max: 90

.vale/styles/Yellow/SpecVoice.yml

@@ -0,0 +1,10 @@
+extends: existence
+message: "Use definitional spec voice instead of narrative phrasing: '%s'."
+level: warning
+ignorecase: true
+tokens:
+  - "\\bwe (?:will|can|should|need to)\\b"
+  - "\\byou (?:will|can|should|need to)\\b"
+  - "\\blet's\\b"
+  - "\\bthis guide (?:shows|walks|explains)\\b"
+  - "\\bin this (?:guide|page|section)\\b"

templates/api-reference-method.md

@@ -0,0 +1,51 @@
+---
+title: <namespace.v1.method>
+description: <One sentence that describes the RPC method.>
+---
+
+# <namespace.v1.method>
+
+<One sentence that states what this method does.>
+
+## Signature
+
+```text
+<namespace.v1.method>(<payload>) -> <response>
+```
+
+## Parameters
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `<field>` | `<type>` | Yes | <Description.> |
+
+## Response
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `<field>` | `<type>` | <Description.> |
+
+## Errors
+
+| Code | Meaning |
+| --- | --- |
+| `<code>` | <Description.> |
+
+## SDK equivalents
+
+| SDK | Call |
+| --- | --- |
+| TypeScript | `<client.method()>` |
+| Go | `<client.Method()>` |
+
+## Example envelope
+
+```json
+[
+  "<type>",
+  "<requestId>",
+  "<namespace.v1.method>",
+  {},
+  "<timestamp>"
+]
+```

templates/build-howto.mdx

@@ -0,0 +1,50 @@
+---
+title: <Task-based title>
+description: <One sentence that says who this is for and what they build.>
+sidebar_position: <n>
+---
+
+# <Task-based title>
+
+<One sentence that states the task this page completes.>
+
+## TL;DR
+
+<Two sentences of context: what problem this solves and what the result does.>
+
+```bash
+<command 1>
+<command 2>
+<command 3>
+```
+
+## Step-by-step
+
+### 1. <First step>
+
+<Imperative instruction.>
+
+```bash
+<command>
+```
+
+<One sentence that confirms what changed.>
+
+### 2. <Second step>
+
+<Imperative instruction.>
+
+```typescript
+<code>
+```
+
+<One sentence that confirms what changed.>
+
+## Verify
+
+<Command, UI state, or API response that confirms success.>
+
+## Next steps
+
+- [<Related Build page>](./<page>)
+- [<API Reference page>](../../api-reference/<page>)

templates/learn-page.mdx

@@ -0,0 +1,23 @@
+---
+title: <Concept title>
+description: <One sentence that says what the concept is and why it matters.>
+protocol_link: ../protocol/<protocol-page>
+---
+
+# <Concept title>
+
+<One sentence that defines the concept in the reader's words.>
+
+<One short analogy paragraph that introduces the concept.>
+
+## Why it matters
+
+<Explain the builder problem this concept solves.>
+
+## How it works
+
+<Describe the model and name the formal v1 terms.>
+
+## Related protocol
+
+Read the formal definition in [<Protocol page>](../protocol/<protocol-page>).

templates/protocol-page.mdx

@@ -0,0 +1,26 @@
+---
+title: <Protocol concept>
+description: <One sentence that states the invariant or model.>
+learn_link: ../learn/<learn-page>
+---
+
+# <Protocol concept>
+
+<One sentence that defines the concept formally.>
+
+## Definition
+
+<Define the concept with v1 terminology.>
+
+## Invariants
+
+- <Invariant.>
+- <Invariant.>
+
+## State transitions
+
+<Describe valid transitions and rejection conditions.>
+
+## Learn counterpart
+
+Read the builder-facing explanation in [<Learn page>](../learn/<learn-page>).

templates/tutorial.mdx

@@ -0,0 +1,51 @@
+---
+title: <Tutorial title>
+description: <One sentence that says what complete app or workflow the reader builds.>
+sidebar_position: <n>
+---
+
+# <Tutorial title>
+
+<One sentence that states the completed outcome.>
+
+## What you build
+
+<Short description of the runnable result.>
+
+## Prerequisites
+
+- <Tool or account.>
+- <Funded test wallet or endpoint.>
+
+## Steps
+
+### 1. <First step>
+
+<Imperative instruction.>
+
+```bash
+<command>
+```
+
+### 2. <Second step>
+
+<Imperative instruction.>
+
+```typescript
+<code>
+```
+
+## Run the app
+
+```bash
+<command>
+```
+
+## What you have now
+
+<Confirm the working app or workflow.>
+
+## Next steps
+
+- [<Related Build page>](../build/<page>)
+- [<API Reference page>](../api-reference/<page>)