[jderochervlk]

This stacks the documentation/distribution work on binding-contract PR #399, which is itself stacked on tooling/release PR #397. It does not publish packages, create tags, close historical backlog issues, or change GitHub/npm settings.

For #393, the README and documentation landing pages distinguish the ReScript 13.0.0-alpha.5 tested baseline from the wider prerelease peer range, document the alpha breaking-change contract, provide a normal install/config/example, and state that the registry alpha tag still points to the older 0.1.0-alpha-b1d58f9 until an authorized alpha.1 publication. The candidate consumer is verified from its packed tarball. Contributor setup uses a fast-forward-only update workflow without destructive cleanup. Architecture, modelling, generation, documentation, and testing guides now describe the flat public API and current fixture/compiler/browser workflow. Project status reconciles #236, #237 and its now-closed slices #240-243, #27, #23, #4, and #5 without closing them or making them alpha gates. CHANGELOG.md records the binding migration contracts from the stacked branch, including typed bytes/audio buffers, WebCrypto helpers, empty and nullable results, operation-specific IndexedDB deletion, and DOM/SVG changes.

For #394, generated signature links resolve through the public API manifest and a unique public type alias owner; ambiguous/internal references remain unlinked. The examples link respects Astro's configured base path. npm run check:docs-links validates required docs routes, local HTML and SVG fragments, page/asset links (including CSS url()/imports and inline styles), and same-site absolute routes; fixtures cover base traversal, duplicate prefixes, comments/strings, escaped CSS identifiers, entity/percent fragments, and empty/incomplete artifacts. CI and the unprivileged release validation job run this checker immediately after the docs build. External URLs and canonical metadata are intentionally not verified by the local route checker.

For #395, repository history and actual WOFF2 metadata did not establish source release/version provenance or applicable licenses for the bundled Inter/Roboto Mono files. The binaries and their dead CSS/layout references are removed rather than assigning an unverified license. The site uses documented system sans-serif/monospace stacks; visual metrics can vary with the reader's installed fonts. The attribution page is emitted in the built docs, and the source-only npm package still excludes documentation assets.

The release guide covers the initial 1.0.0-alpha.1 version/tag, later synchronized package/lock bumps, release notes, the tested check sequence, exact-artifact validation and dry-run, main/manual publication guard, and post-publish dist-tag check. The npm trusted-publisher tuple is recorded, but npm account configuration/provenance setup remains an explicit maintainer-only check; #385 is not claimed fully complete by this documentation change. The local registry alpha tag is still on the prior prerelease, and no publication was performed.

Closes #393
Closes #394
Closes #395

[jderochervlk]

Independent review — bdff32eaa9eeea8cdd8ac9e00488f9c996cba593

Reviewed against tooling base 77b59836d6ef1838795f78496f7dd89cd98816de, including the CSS-check follow-up after the initially requested 36ec0c0 snapshot. Keep draft / changes requested in this summary; this is not a same-account formal approval. No source files, settings, releases, or branches were changed.

Actionable findings

1. P2 — Resolve relative references against the deployed page URL, including the base. scripts/check-doc-links.mjs:124–134. pageURL omits the deployment base, then the fallback accepts paths outside it. With base /docs/, documents index.html containing <a href="../guide/"> plus guide/index.html return [], although the browser navigates to /guide/, outside the deployment. Conversely href="docs/guide/" also falsely passes by stripping what is actually a duplicated prefix. Construct the source URL under the real normalized base and enforce containment after resolution. Also fix root-base normalization: / becomes //, incorrectly rejecting valid root-relative links. Add negative traversal/duplicate-prefix and root-base fixtures.

2. P2 — Correct the historical disposition of Simplify package module/type structure #237 using its child issues, not its stale checkbox text. docs/content/docs/project-status.mdx:48–50. The page says fetch/file/canvas/URL/socket, capability access, media, and integration remain. Live Simplify fetch, file, canvas, URL, and socket module surfaces #240, Move runtime capability access away from Global window and navigator #241, Simplify media and device module surfaces #243, and Final integration for package simplification #242 are all closed, as are Simplify DOM, event, and observer module surfaces #238/Shared groundwork for package simplification #239. Record the completed slices and identify any concrete residual work separately; the open parent and unchecked historical list do not establish those slices remain unfinished. This is part of Document the ReScript 13 alpha contract and safe contributor workflow #393's explicit reconciliation acceptance.

3. P2 — Tokenize CSS references rather than matching url() inside arbitrary text. scripts/check-doc-links.mjs:107–112. Both /* old: url(/docs/removed.woff2) */ and a::before { content: "url(/docs/not-a-link)" } produce missing-asset errors, despite neither requesting an asset. Conversely the valid escaped CSS function u\72l(/docs/missing.svg) is missed. Decode CSS escapes, ignore comments and non-URL string tokens, and do not HTML-decode raw stylesheet text. Add failing-target as well as successful fixtures; the new fixture only tests success.

4. P2 — Restrict alias candidates to actual exported top-level types. docs/typeLinks.js:1–5. The regex scans comments and nested modules. /**\ntype example = Internal.real\n*/\ntype t = Internal.real suppresses the valid unique public t as ambiguous; a nested module Impl with type hidden = Internal.secret on its own indented line produces a nonexistent top-level PublicOwner#hidden target. Use exported documentation/compiler items, or a parser that excludes comments/nested declarations and respects interfaces; verify the candidate anchor exists before linking. These are reproduced parser-boundary defects, not a claim that the current site contains such broken alias links: all 77 current unique candidate anchors existed.

5. P2 — Make fragment/attribute normalization browser-compatible and handle malformed escapes explicitly. scripts/check-doc-links.mjs:8–9 and 124–142. <a href="#caf%C3%A9"> targeting id="café" incorrectly fails because numeric character references are not decoded. href="#%" or a malformed path escape throws URIError, aborting the whole audit without a source/reference diagnostic; a literal-percent fragment can itself be browser-valid. Use proper HTML entity decoding and explicit, tolerant/error-valued URI handling. Add Unicode/numeric-entity, literal-percent, malformed-path, and malformed-fragment fixtures.

6. P2 — Fail when the supplied built artifact contains no HTML. scripts/check-doc-links.mjs:190–204. Running the CLI against an empty existing directory exits successfully with Validated ... in 0 built files. An asset-only directory likewise supplies no page-validation evidence. Require at least the expected entry page/HTML set before reporting successful validation, with empty/asset-only fixture tests.

7. P2 — Make the release guide's exact-artifact local dry-run recipe achievable. docs/content/docs/contributing/releasing.mdx:45–49 instructs maintainers to use the archive produced by the workflow and forbids repacking. At this exact stack, the workflow packs into a runner-local .release directory and has no artifact upload/download step. Explain how the validated archive is retrieved, or reconcile this guidance after the foundation supplies artifact transfer. Do not imply that an independently repacked local archive is the same validated artifact.

Lower-priority cleanup / scope gaps

• P3 — Orphan font references remain: docs/styles/fonts.css:1–7 through line 106 still reference all seven deleted WOFF2 files; unused docs/layouts/BaseLayout.astro:2 still imports @fontsource-variable/inter. Remove or reconcile these dead paths. They are not presently bundled: the built artifact contains no font binaries or active WOFF2 references.
• P3 — Contributor architecture is only partially refreshed: api-module-structure.mdx:28–29 implies every interface owner exports t, which is not true for e.g. current FontFace/ResizeObserver. The companion module-type-structure.mdx:42–65 still teaches open DOMAPI and old paths; api-modelling.mdx:101 still anticipates a Vitest/happy-dom harness rather than the actual native-browser direction. Qualify the contract and refresh or clearly mark historical examples.
• Additional explicit checker limits: only .html fragments are validated, so an existing icons.svg#missing passes; every scheme-bearing URL, including absolute same-site URLs, is excluded. Do not interpret a local-check pass as verification of those targets.

Acceptance and release gates

• Document the ReScript 13 alpha contract and safe contributor workflow #393: partial, not ready to close. Compiler baseline/range, alpha-breaking contract, minimum candidate configuration/example, safe fast-forward update recipe, and restrained runtime/browser claims are supported. Historical/architecture corrections remain. The PR body explicitly says final binding migration reconciliation is pending: that is clear enough to explain draft status, not evidence that migration acceptance is complete. Keep it pending, put a corresponding warning in CHANGELOG.md:14–41, and reconcile the final bindings before readiness. In particular the current notes do not yet cover the listed Web Audio breaking typed-buffer contracts or the nullable/empty/IndexedDB result migrations from Represent native empty, nullable, and operation-specific results accurately #392. Those should not disappear merely because the final branch is still in progress.
• Live installation is not yet candidate acceptance: README.md:16–17 currently installs registry alpha = 0.1.0-alpha-b1d58f9, whose peer is rescript >=13; the exact first README command failed with ETARGET. The new candidate tarball succeeds. Label the registry command as applicable after the separately authorized candidate publication, and do not claim it is a live installation pass now. This is not a request to publish during review.
• Resolve generated API links to public pages and check built documentation #394: actual generated-site repair works, checker acceptance remains partial. Public-page filtering is retained, no top-level internal *Types routes leak, the example guide link contains the correct deployment base, and current emitted local links/fragments pass. The counterexamples above show remaining false-green/false-failure behavior.
• Include provenance and license notices for bundled documentation fonts #395: system-font alternative satisfies the distribution/license goal. The seven unverifiable binaries are gone; the attribution page is emitted/discoverable; the site uses system stacks; the checked npm tarball excludes docs/fonts/tools. No guessed Inter/Roboto license needs to be assigned to binaries that are no longer distributed. Dead-reference cleanup remains.
• Release/trust: not verified. The guide correctly calls npm account settings unverified and restricts alpha guidance to the alpha dist-tag. I did not verify trusted publishing, successful provenance-bearing publication, or external-site availability. Also, the pinned foundation still has one publish job granting id-token: write to PR/dry-run validation; the isolation described in test(webapi): harden runtime and release validation [Codex] #397's body is not present in the reviewed YAML. This is inherited foundation work, not introduced by the three-line integration here; keep that tooling/release gate open and re-review after the stack updates. Registry dist-tags do not prove publisher trust or provenance.

Evidence

All validation ran in disposable scratch copies of the exact commits, leaving the attached source worktree untouched (its pre-existing deletion of tests/index.js remains unchanged). Local toolchain: Node 24.16.0 / npm 11.15.0 / ReScript 13.0.0-alpha.5, not the CI Node 26 environment.

At bdff32e: npm run build, npm run build:docs, npm run check:docs-links (9 fixtures; 307 HTML pages / 675 built files), npm run format:check, and npm run check:consumer passed. The consumer check validated 343 tarball files, supported installation, unsupported-peer rejection, default/Fetch/SafeFetch compilation, feature rejection, runtime smoke, and the registered negative diagnostic fixture. Separately compiled the README's exact minimal configuration/example against the candidate tarball; it succeeds. Ran the edge-case probes described above. An independent HTMLParser audit of the unchanged generated HTML also checked local fragments; its only additional missing same-site URL was Astro's absolute canonical /404/ versus emitted 404.html, not a newly broken navigation link.

I did not run the full Node/browser suites, feature suite, Node 26 toolchain, or a browser compatibility matrix. External links are outside the local check; in particular the new GitHub main/CHANGELOG.md link is currently 404 before merge. That pre-merge fact is not a permanent broken-link finding, but it is also not validated by the local link gate.