Document nested relationship filters and pagination

.github/workflows/claude-review.yml

@@ -89,8 +89,10 @@ jobs:
         - **Redirects**: `historic-redirects.ts` keeps old URLs alive. Renaming or
           moving a page without a redirect breaks external links.
         - **Tooling**: `npm run typecheck` (tsc) and `format:check` (prettier).
-          `npm run lint` is a no-op stub (`echo 0`) — do not treat a green lint as
-          evidence of anything.
+          `npm run lint` runs oxlint with warnings treated as errors. The separate
+          `npm run test:examples` check runs documented-example and fixture-fetch
+          tests, including live companion-fixture parity in CI. It does not execute
+          Harper; the companion core suite owns native HTTP response verification.
         - Do not comment on formatting; prettier owns it.
     secrets:
       ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

.github/workflows/gemini-review.yml

@@ -94,8 +94,10 @@ jobs:
         - **Redirects**: `historic-redirects.ts` keeps old URLs alive. Renaming or
           moving a page without a redirect breaks external links.
         - **Tooling**: `npm run typecheck` (tsc) and `format:check` (prettier).
-          `npm run lint` is a no-op stub (`echo 0`) — do not treat a green lint as
-          evidence of anything.
+          `npm run lint` runs oxlint with warnings treated as errors. The separate
+          `npm run test:examples` check runs documented-example and fixture-fetch
+          tests, including live companion-fixture parity in CI. It does not execute
+          Harper; the companion core suite owns native HTTP response verification.
         - Do not comment on formatting; prettier owns it.
     secrets:
       GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}

.github/workflows/validate.yaml

@@ -9,6 +9,9 @@ concurrency:
   group: validate-${{ github.event.pull_request.number }}
   cancel-in-progress: true
 
+permissions:
+  contents: read
+
 jobs:
   validate:
     name: ${{ matrix.check }}
@@ -40,3 +43,8 @@ jobs:
         run: npm ci
       - name: Run ${{ matrix.check }}
         run: npm run ${{ matrix.command }}
+      - name: Run example tests
+        if: matrix.command == 'lint'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: npm run test:examples

.oxlintrc.json

@@ -0,0 +1,3 @@
+{
+	"ignorePatterns": ["static/js/reo.js"]
+}

AGENTS.md

@@ -16,7 +16,8 @@ Review `README.md` and `CONTRIBUTING.md` for all relevant repository information
 - Prettier is configured via `@harperfast/code-guidelines/prettier` (see `package.json`).
 - **Required before every commit/PR:** run `npm run format:write`, then confirm `npm run format:check` is clean. This is a hard gate, not advisory — CI fails any unformatted PR (see [CI](#ci)).
 - Formatting applies to **every file in the repo**, not just content. Prettier runs against the whole tree (`prettier .`) — `.ts`, `.md`, `.mdx`, `.json`, and files under `plans/`, `scripts/`, etc. Do not assume a directory is exempt because it is not user-facing docs.
-- The lint script is a no-op (`echo 0`); do not expect `npm run lint` to catch issues.
+- `npm run lint` runs oxlint over JavaScript and TypeScript with warnings treated as errors.
+- `npm run test:examples` separately runs documented-example checks and fixture-fetch reliability tests. In CI, it also compares fixtures against the companion core revision; locally set `HARPER_CORE_FIXTURE_ROOT` to compare an offline core checkout.
 
 ## Content Style
 
@@ -65,7 +66,7 @@ Prefer plain ASCII characters in Markdown unless a typographic character is genu
 
 ## Testing
 
-- There is no automated test suite. Verification is done by running the dev server or build.
+- `npm run test:examples` checks the documented requests/responses and fixture-fetch behavior; `npm run test:workflows` checks companion workflow scenarios. The companion core suite executes the request/response fixtures against Harper.
 - `npm run build` is the best end-to-end check — it will fail on broken links, missing imports, or MDX errors.
 - `npm run typecheck` checks TypeScript config files only.
 - Known issue: `npm run serve` (post-build preview) 404s on paths like `/docs/4.X` locally due to an upstream `serve-handler` bug. This is not a real breakage — see CONTRIBUTING.md for details.
@@ -75,7 +76,7 @@ Prefer plain ASCII characters in Markdown unless a typographic character is genu
 
 ## CI
 
-- CI runs `npm run build` and `npm run format:check` on pull requests.
+- CI runs the production build, TypeScript Check, Lint Check, Format Check and Workflow Tests on pull requests. Lint Check receives a read-only token for the live companion-fixture comparison.
 - If CI fails on formatting, run `npm run format:write` locally and commit the result.
 
 ## Issues & Project Management

CONTRIBUTING.md

@@ -21,7 +21,7 @@ You don't need to get type, area, or milestone exactly right when filing — mai
 
 Before contributing, please ensure you have the following installed:
 
-- Node.js (version 22)
+- Node.js (version 22.12.0 or later; `.node-version` selects Node 24)
 - npm (version 10 - included with Node.js)
 
 ## Set Up
@@ -61,6 +61,12 @@ npm run format:check
 
 CI runs `npm run format:check` on every pull request and will fail if anything is unformatted. If CI fails on formatting, run `npm run format:write` locally and commit the result. Prettier is configured via `@harperfast/code-guidelines/prettier` (see `package.json`).
 
+## Code Checks
+
+Run `npm run lint` to lint JavaScript and TypeScript with oxlint. Warnings fail the check. The vendor-provided Reo loader (`static/js/reo.js`) is excluded.
+
+Run `npm run test:examples` separately to validate the executable nested-relationship examples and fixture-fetch helper. CI runs both commands as separate steps in the required Lint Check job.
+
 ## Site Organization
 
 This site is powered by Docusaurus. The documentation is split into four distinct sections, each serving a different purpose and configured as its own Docusaurus plugin instance.

package.json

@@ -18,8 +18,9 @@
 		"format": "prettier .",
 		"format:check": "npm run format -- --check",
 		"format:write": "npm run format -- --write",
-		"lint": "echo 0;",
+		"lint": "oxlint --deny-warnings .",
 		"preview:pr": "node scripts/preview-pr.mjs",
+		"test:examples": "node --test scripts/nested-relationship-examples.test.mjs scripts/github-fixture-fetch.test.mjs",
 		"test:workflows": "node scripts/companion-check.test.mjs"
 	},
 	"devDependencies": {
@@ -38,6 +39,7 @@
 		"@mdx-js/react": "3.1.1",
 		"@signalwire/docusaurus-plugin-llms-txt": "1.2.2",
 		"clsx": "2.1.1",
+		"oxlint": "1.31.0",
 		"prettier": "3.8.1",
 		"prism-react-renderer": "2.4.1",
 		"react": "19.2.4",
@@ -57,7 +59,7 @@
 		]
 	},
 	"engines": {
-		"node": ">=22"
+		"node": ">=22.12.0"
 	},
 	"prettier": "@harperfast/code-guidelines/prettier",
 	"license": "Apache-2.0"