YNU-864: Nitrolite v1 docs reorg

.github/workflows/vale.yml

@@ -0,0 +1,45 @@
+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
+
+jobs:
+  vale:
+    name: Vale advisory lint
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Install Vale
+        run: |
+          VALE_VERSION=3.14.2
+          curl -sSL "https://github.com/errata-ai/vale/releases/download/v${VALE_VERSION}/vale_${VALE_VERSION}_Linux_64-bit.tar.gz" -o /tmp/vale.tar.gz
+          tar -xzf /tmp/vale.tar.gz -C /tmp vale
+          sudo mv /tmp/vale /usr/local/bin/vale
+          vale --version
+
+      - name: Run Vale
+        run: |
+          vale sync
+          set +e
+          vale --minAlertLevel=error docs templates
+          status=$?
+          if [ "$status" -ne 0 ]; then
+            echo "::warning::Vale found advisory issues. See the log above."
+          fi
+          exit 0

.gitignore

@@ -21,3 +21,4 @@ npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
 .vercel
+.gstack/

.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,19 @@
+StylesPath = .vale/styles
+MinAlertLevel = suggestion
+
+[formats]
+mdx = md
+
+[*.{md,mdx}]
+BasedOnStyles = Yellow
+
+# Quadrant-specific rules. Off by default; per-folder overlays opt in.
+Yellow.NoMetaphor = NO
+Yellow.SpecVoice = NO
+Yellow.NoNarrative = NO
+Yellow.LearnCrossLink = NO
+Yellow.ProtocolCrossLink = NO
+Yellow.BuildPageShapeTLDR = NO
+Yellow.BuildPageShapeStepByStep = NO
+Yellow.BuildPageShapeVerify = NO
+Yellow.BuildPageShapeNextSteps = NO

.vale/styles/Yellow/AISlop.yml

@@ -0,0 +1,33 @@
+extends: existence
+message: "Avoid '%s'. Use direct, concrete wording."
+level: error
+ignorecase: true
+tokens:
+  - "—"
+  - "–"
+  - "\\bdelve\\b"
+  - "\\bleverage\\b"
+  - "\\bharness(?:es|ed|ing)?\\s+(?:the|your|its|our|all|this|these|those|every|any)\\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/BuildPageShapeNextSteps.yml

@@ -0,0 +1,6 @@
+extends: occurrence
+message: "Build how-to pages must include a '## Next steps' heading."
+level: error
+scope: raw
+token: "(?m)^## Next steps\\b"
+min: 1

.vale/styles/Yellow/BuildPageShapeStepByStep.yml

@@ -0,0 +1,6 @@
+extends: occurrence
+message: "Build how-to pages must include a '## Step-by-step' heading."
+level: error
+scope: raw
+token: "(?m)^## Step-by-step\\b"
+min: 1

.vale/styles/Yellow/BuildPageShapeTLDR.yml

@@ -0,0 +1,6 @@
+extends: occurrence
+message: "Build how-to pages must include a '## TL;DR' heading."
+level: error
+scope: raw
+token: "(?m)^## TL;DR\\b"
+min: 1

.vale/styles/Yellow/BuildPageShapeVerify.yml

@@ -0,0 +1,6 @@
+extends: occurrence
+message: "Build how-to pages must include a '## Verify' heading."
+level: error
+scope: raw
+token: "(?m)^## Verify\\b"
+min: 1

.vale/styles/Yellow/LearnCrossLink.yml

@@ -0,0 +1,6 @@
+extends: occurrence
+message: "Learn pages must declare 'protocol_link' in frontmatter to point at their Protocol counterpart."
+level: error
+scope: raw
+token: "(?m)^protocol_link:"
+min: 1

.vale/styles/Yellow/NeedBasedLabels.yml

@@ -0,0 +1,10 @@
+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"

.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/ProtocolCrossLink.yml

@@ -0,0 +1,6 @@
+extends: occurrence
+message: "Protocol pages must declare 'learn_link' in frontmatter to point at their Learn counterpart."
+level: error
+scope: raw
+token: "(?m)^learn_link:"
+min: 1

.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"

AGENTS.md

@@ -0,0 +1,7 @@
+# Codex Instructions for yellow-docs
+
+- For Docusaurus changes, run `npm run typecheck` and `npm run build`.
+- After build, run a local Docusaurus server with `npm run serve -- --host 127.0.0.1 --port <free-port>` and fetch each changed public route with `curl -fsS -L`.
+- For navigation or versioning changes, fetch both current and versioned routes and confirm the expected links, labels, and version switch targets appear in the returned HTML.
+- Internal Docusaurus doc links should be extensionless. Do not add `.md` or `.mdx` suffixes to Markdown links unless linking to a raw file intentionally.
+- For Nitrolite protocol docs, keep content language-agnostic and source-bound to `/Users/maharshimishra/Documents/nitrolite/docs/protocol`.

README.md

@@ -39,3 +39,23 @@ GIT_USER=<Your GitHub username> yarn deploy
 ```
 
 If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
+
+## Site Architecture
+
+This site hosts two product docs as separate sub-sites under one Docusaurus instance:
+
+- **`/nitrolite/*`** — State channel SDK docs (versioned 1.x / 0.5.x)
+- **`/clearnet/*`** — Decentralized clearing protocol docs (unversioned)
+- **`/`** — Portal landing page linking to both sub-sites
+
+Source layout:
+
+- `docs/nitrolite/` — Nitrolite content (managed by the preset's docs plugin)
+- `docs/clearnet/` — Clearnet content (managed by a second `@docusaurus/plugin-content-docs` instance, id: `clearnet`)
+- `sidebars-nitrolite.ts` / `sidebars-clearnet.ts` — sidebar configs per sub-site
+- `src/theme/Navbar/Content/` — swizzled component that filters top-navbar items by current path (via `customProps.showOn`)
+
+### Known Limitations
+
+- **Search**: lunr-search uses a single index across both sub-sites. A query from `/nitrolite/...` may surface Clearnet results and vice versa. To scope search per sub-site, replace lunr-search with Algolia (separate indices) or a custom search component.
+- **Versioned docs links**: `versioned_docs/version-0.5.x/` is a historical snapshot and still contains `/docs/...` links from when the site lived under that path. Those links break under the new `/nitrolite/0.5.x/...` routing. Either rewrite versioned content links or accept them as archived.