diff --git a/cli/src/main/java/io/github/dfa1/vortex/cli/CliHandles.java b/cli/src/main/java/io/github/dfa1/vortex/cli/CliHandles.java
index 4e800d21..1c9d9b4b 100644
--- a/cli/src/main/java/io/github/dfa1/vortex/cli/CliHandles.java
+++ b/cli/src/main/java/io/github/dfa1/vortex/cli/CliHandles.java
@@ -15,7 +15,7 @@
 
 /// Shared handle plumbing for the interactive subcommands (`view`, `tui`).
 ///
-/// A {@link VortexReader} uses a confined {@link java.lang.foreign.Arena}, so the file must be
+/// A [VortexReader] uses a confined [java.lang.foreign.Arena], so the file must be
 /// opened and closed on the same {@link IoWorker} thread the TUI later dispatches I/O to. These
 /// helpers centralise that worker round-trip plus the local-file / http(s) target resolution.
 @SuppressWarnings("java:S106") // CLI tool: user-facing diagnostics go to System.err by design.
@@ -55,7 +55,7 @@ static Optional<VortexHandle> openOnWorker(IoWorker worker, String target)
     static void closeOnWorker(IoWorker worker, VortexHandle handle) {
         try {
             worker.runAndAwait(handle::close);
-        } catch (InterruptedException e) {
+        } catch (InterruptedException _) {
             Thread.currentThread().interrupt();
         }
     }
@@ -84,7 +84,7 @@ private static VortexHandle open(String target) throws IOException {
         if (target.startsWith("http://") || target.startsWith("https://")) {
             try {
                 return VortexHttpReader.open(new URI(target));
-            } catch (URISyntaxException e) {
+            } catch (URISyntaxException _) {
                 System.err.println("invalid URL: " + target);
                 return null;
             }
diff --git a/cli/src/main/java/io/github/dfa1/vortex/cli/FilterCommand.java b/cli/src/main/java/io/github/dfa1/vortex/cli/FilterCommand.java
index 7b5e6416..61df260b 100644
--- a/cli/src/main/java/io/github/dfa1/vortex/cli/FilterCommand.java
+++ b/cli/src/main/java/io/github/dfa1/vortex/cli/FilterCommand.java
@@ -131,11 +131,11 @@ private static IllegalArgumentException invalid(String expr) {
     private static Comparable<?> parseValue(String raw) {
         try {
             return Long.parseLong(raw);
-        } catch (NumberFormatException ignored) {
+        } catch (NumberFormatException _) {
         }
         try {
             return Double.parseDouble(raw);
-        } catch (NumberFormatException ignored) {
+        } catch (NumberFormatException _) {
         }
         if ("true".equalsIgnoreCase(raw)) {
             return Boolean.TRUE;
diff --git a/cli/src/main/java/io/github/dfa1/vortex/cli/InspectCommand.java b/cli/src/main/java/io/github/dfa1/vortex/cli/InspectCommand.java
index 8899bfc3..4573ac51 100644
--- a/cli/src/main/java/io/github/dfa1/vortex/cli/InspectCommand.java
+++ b/cli/src/main/java/io/github/dfa1/vortex/cli/InspectCommand.java
@@ -54,7 +54,7 @@ private static VortexHandle open(String target) throws IOException {
         if (target.startsWith("http://") || target.startsWith("https://")) {
             try {
                 return VortexHttpReader.open(new URI(target));
-            } catch (URISyntaxException e) {
+            } catch (URISyntaxException _) {
                 System.err.println("invalid URL: " + target);
                 return null;
             }
diff --git a/cli/src/main/java/io/github/dfa1/vortex/cli/VortexCli.java b/cli/src/main/java/io/github/dfa1/vortex/cli/VortexCli.java
index 1fe49ed7..212e1a97 100644
--- a/cli/src/main/java/io/github/dfa1/vortex/cli/VortexCli.java
+++ b/cli/src/main/java/io/github/dfa1/vortex/cli/VortexCli.java
@@ -6,7 +6,7 @@
 
 /// Entry point for the Vortex command-line tool.
 ///
-/// Exit codes: see {@link ExitStatus}.
+/// Exit codes: see [ExitStatus].
 public final class VortexCli {
 
     static {
diff --git a/cli/src/main/java/io/github/dfa1/vortex/cli/tui/IoWorker.java b/cli/src/main/java/io/github/dfa1/vortex/cli/tui/IoWorker.java
index 429d6d01..7bf3ff68 100644
--- a/cli/src/main/java/io/github/dfa1/vortex/cli/tui/IoWorker.java
+++ b/cli/src/main/java/io/github/dfa1/vortex/cli/tui/IoWorker.java
@@ -5,7 +5,7 @@
 import java.util.concurrent.LinkedBlockingQueue;
 import java.util.concurrent.atomic.AtomicInteger;
 
-/// Single-threaded I/O executor that owns one {@link io.github.dfa1.vortex.reader.VortexHandle}.
+/// Single-threaded I/O executor that owns one [io.github.dfa1.vortex.reader.VortexHandle].
 ///
 /// Vortex readers use a confined {@link java.lang.foreign.Arena}, so every
 /// `slice()` / `scan()` call must happen on the same thread that
@@ -88,13 +88,13 @@ private void loop() {
             Runnable task;
             try {
                 task = queue.take();
-            } catch (InterruptedException e) {
+            } catch (InterruptedException _) {
                 Thread.currentThread().interrupt();
                 return;
             }
             try {
                 task.run();
-            } catch (RuntimeException ignored) {
+            } catch (RuntimeException _) {
                 // Task is expected to capture its own failures into shared state.
             }
         }
diff --git a/cli/src/main/java/io/github/dfa1/vortex/cli/tui/VortexInspectorTui.java b/cli/src/main/java/io/github/dfa1/vortex/cli/tui/VortexInspectorTui.java
index 4d93837e..3f76751a 100644
--- a/cli/src/main/java/io/github/dfa1/vortex/cli/tui/VortexInspectorTui.java
+++ b/cli/src/main/java/io/github/dfa1/vortex/cli/tui/VortexInspectorTui.java
@@ -61,7 +61,7 @@ public static void show(VortexHandle handle, InspectorTree.Progress progress) th
     }
 
     /// Variant that dispatches every `handle` I/O call onto the supplied
-    /// {@link IoWorker}. Required when the handle was opened on a different
+    /// [IoWorker]. Required when the handle was opened on a different
     /// thread (Vortex readers use a confined {@link java.lang.foreign.Arena},
     /// so cross-thread access throws `WrongThreadException`).
     ///
@@ -166,7 +166,7 @@ private void indexStatsChildrenOnWorker(InspectorTree.Node root) {
             }
             try {
                 worker.runAndAwait(() -> indexStatsChildren(root));
-            } catch (InterruptedException e) {
+            } catch (InterruptedException _) {
                 Thread.currentThread().interrupt();
             }
         }
diff --git a/cli/src/main/java/io/github/dfa1/vortex/cli/tui/term/PosixTerminal.java b/cli/src/main/java/io/github/dfa1/vortex/cli/tui/term/PosixTerminal.java
index 4aa17194..2cf5a5e0 100644
--- a/cli/src/main/java/io/github/dfa1/vortex/cli/tui/term/PosixTerminal.java
+++ b/cli/src/main/java/io/github/dfa1/vortex/cli/tui/term/PosixTerminal.java
@@ -104,7 +104,7 @@ public Size size() {
             if (rc != 0) {
                 return new Size(24, 80);
             }
-        } catch (Throwable t) {
+        } catch (Throwable _) {
             return new Size(24, 80);
         }
         int rows = Short.toUnsignedInt(ws.get(ValueLayout.JAVA_SHORT, 0));
@@ -143,7 +143,7 @@ public void close() {
         closed = true;
         try {
             Runtime.getRuntime().removeShutdownHook(shutdownHook);
-        } catch (IllegalStateException ignored) {
+        } catch (IllegalStateException _) {
             // JVM already shutting down.
         }
         restore();
@@ -158,7 +158,7 @@ private void restore() {
             out.flush();
             @SuppressWarnings("unused")
             int rc = (int) TCSETATTR.invokeExact(STDIN_FD, TCSANOW, savedTermios);
-        } catch (Throwable ignored) {
+        } catch (Throwable _) {
             // Best-effort: JVM is exiting; nothing useful to do.
         }
     }
diff --git a/cli/src/main/java/io/github/dfa1/vortex/cli/tui/term/WindowsTerminal.java b/cli/src/main/java/io/github/dfa1/vortex/cli/tui/term/WindowsTerminal.java
index a194f17c..02d14125 100644
--- a/cli/src/main/java/io/github/dfa1/vortex/cli/tui/term/WindowsTerminal.java
+++ b/cli/src/main/java/io/github/dfa1/vortex/cli/tui/term/WindowsTerminal.java
@@ -136,7 +136,7 @@ public Size size() {
             if (rc == 0) {
                 return new Size(24, 80);
             }
-        } catch (Throwable t) {
+        } catch (Throwable _) {
             return new Size(24, 80);
         }
         int left = info.get(ValueLayout.JAVA_SHORT, 10);
@@ -179,7 +179,7 @@ public void close() {
         closed = true;
         try {
             Runtime.getRuntime().removeShutdownHook(shutdownHook);
-        } catch (IllegalStateException ignored) {
+        } catch (IllegalStateException _) {
             // JVM already shutting down.
         }
         restore();
diff --git a/cli/src/test/java/io/github/dfa1/vortex/cli/tui/term/PosixTerminalSmokeTest.java b/cli/src/test/java/io/github/dfa1/vortex/cli/tui/term/PosixTerminalSmokeTest.java
index ea137fbc..30cb57ad 100644
--- a/cli/src/test/java/io/github/dfa1/vortex/cli/tui/term/PosixTerminalSmokeTest.java
+++ b/cli/src/test/java/io/github/dfa1/vortex/cli/tui/term/PosixTerminalSmokeTest.java
@@ -9,7 +9,7 @@
 /// Smoke test for the FFM-based POSIX terminal binding.
 ///
 /// Runs only on Linux / macOS (other OSes lack the libc entry points). Mirrors
-/// {@link WindowsTerminalSmokeTest}: the goal is to catch missing-symbol /
+/// [WindowsTerminalSmokeTest]: the goal is to catch missing-symbol /
 /// signature-mismatch regressions in CI without requiring a real interactive TTY.
 ///
 /// `open()` and `size()` are deliberately not exercised — they need a real
diff --git a/cli/src/test/java/io/github/dfa1/vortex/cli/tui/term/WindowsTerminalSmokeTest.java b/cli/src/test/java/io/github/dfa1/vortex/cli/tui/term/WindowsTerminalSmokeTest.java
index 20592bbc..179b7f58 100644
--- a/cli/src/test/java/io/github/dfa1/vortex/cli/tui/term/WindowsTerminalSmokeTest.java
+++ b/cli/src/test/java/io/github/dfa1/vortex/cli/tui/term/WindowsTerminalSmokeTest.java
@@ -14,7 +14,7 @@
 ///
 /// - Class load alone forces every `Linker.downcallHandle` to resolve
 ///   its kernel32 symbol. A missing entry point throws
-///   {@link UnsatisfiedLinkError} during static initialization.
+///   [UnsatisfiedLinkError] during static initialization.
 /// - Bit-flag math for the VT mode toggles is verified directly so a typo
 ///   in a constant fails here, not in a customer's terminal.
 class WindowsTerminalSmokeTest {
diff --git a/core/src/main/java/io/github/dfa1/vortex/core/DType.java b/core/src/main/java/io/github/dfa1/vortex/core/DType.java
index b8e29497..6cba7390 100644
--- a/core/src/main/java/io/github/dfa1/vortex/core/DType.java
+++ b/core/src/main/java/io/github/dfa1/vortex/core/DType.java
@@ -25,7 +25,7 @@ public sealed interface DType
     boolean nullable();
 
     /// Returns a copy of this type marked nullable. Sugar over
-    /// {@link #withNullable(boolean)} so call sites read as a fluent adjective:
+    /// [#withNullable(boolean)] so call sites read as a fluent adjective:
     /// `DType.i64().asNullable()`.
     ///
     /// @return a new {@link DType} identical to this one but with `nullable = true`
@@ -36,7 +36,7 @@ default DType asNullable() {
     /// Returns a copy of this type with the given nullability.
     ///
     /// @param nullable the desired nullability for the returned type
-    /// @return a new {@link DType} identical to this one except for its nullability
+    /// @return a new [DType] identical to this one except for its nullability
     default DType withNullable(boolean nullable) {
         return switch (this) {
             case Null _ -> new Null(nullable);
@@ -59,94 +59,94 @@ default DType withNullable(boolean nullable) {
     // [#nullable()] for nullable columns. The underlying records are unchanged
     // and remain usable directly (pattern matching, proto serialization, tests).
 
-    /// @return non-nullable {@link Bool}
+    /// @return non-nullable [Bool]
     static Bool bool_() {
         return new Bool(false);
     }
 
-    /// @return non-nullable {@link Utf8}
+    /// @return non-nullable [Utf8]
     static Utf8 utf8() {
         return new Utf8(false);
     }
 
-    /// @return non-nullable {@link Binary}
+    /// @return non-nullable [Binary]
     static Binary binary() {
         return new Binary(false);
     }
 
-    /// @return non-nullable {@link Null}
+    /// @return non-nullable [Null]
     static Null null_() {
         return new Null(false);
     }
 
-    /// @return non-nullable {@link Variant}
+    /// @return non-nullable [Variant]
     static Variant variant() {
         return new Variant(false);
     }
 
-    /// @return non-nullable {@link Primitive} of {@link PType#I8}
+    /// @return non-nullable [Primitive] of [PType#I8]
     static Primitive i8() {
         return new Primitive(PType.I8, false);
     }
 
-    /// @return non-nullable {@link Primitive} of {@link PType#I16}
+    /// @return non-nullable [Primitive] of [PType#I16]
     static Primitive i16() {
         return new Primitive(PType.I16, false);
     }
 
-    /// @return non-nullable {@link Primitive} of {@link PType#I32}
+    /// @return non-nullable [Primitive] of [PType#I32]
     static Primitive i32() {
         return new Primitive(PType.I32, false);
     }
 
-    /// @return non-nullable {@link Primitive} of {@link PType#I64}
+    /// @return non-nullable [Primitive] of [PType#I64]
     static Primitive i64() {
         return new Primitive(PType.I64, false);
     }
 
-    /// @return non-nullable {@link Primitive} of {@link PType#U8}
+    /// @return non-nullable [Primitive] of [PType#U8]
     static Primitive u8() {
         return new Primitive(PType.U8, false);
     }
 
-    /// @return non-nullable {@link Primitive} of {@link PType#U16}
+    /// @return non-nullable [Primitive] of [PType#U16]
     static Primitive u16() {
         return new Primitive(PType.U16, false);
     }
 
-    /// @return non-nullable {@link Primitive} of {@link PType#U32}
+    /// @return non-nullable [Primitive] of [PType#U32]
     static Primitive u32() {
         return new Primitive(PType.U32, false);
     }
 
-    /// @return non-nullable {@link Primitive} of {@link PType#U64}
+    /// @return non-nullable [Primitive] of [PType#U64]
     static Primitive u64() {
         return new Primitive(PType.U64, false);
     }
 
-    /// @return non-nullable {@link Primitive} of {@link PType#F16}
+    /// @return non-nullable [Primitive] of [PType#F16]
     static Primitive f16() {
         return new Primitive(PType.F16, false);
     }
 
-    /// @return non-nullable {@link Primitive} of {@link PType#F32}
+    /// @return non-nullable [Primitive] of [PType#F32]
     static Primitive f32() {
         return new Primitive(PType.F32, false);
     }
 
-    /// @return non-nullable {@link Primitive} of {@link PType#F64}
+    /// @return non-nullable [Primitive] of [PType#F64]
     static Primitive f64() {
         return new Primitive(PType.F64, false);
     }
 
     /// @param precision total number of significant decimal digits
     /// @param scale     number of digits to the right of the decimal point
-    /// @return non-nullable {@link Decimal}
+    /// @return non-nullable [Decimal]
     static Decimal decimal(int precision, int scale) {
         return new Decimal((byte) precision, (byte) scale, false);
     }
 
-    /// Returns a fresh {@link StructBuilder} for assembling a {@link Struct} dtype with
+    /// Returns a fresh [StructBuilder] for assembling a [Struct] dtype with
     /// name+type pairs declared together at the call site.
     ///
     /// ```java
@@ -163,7 +163,7 @@ static StructBuilder structBuilder() {
         return new StructBuilder();
     }
 
-    /// Fluent builder for {@link Struct} dtypes. Use {@link #structBuilder()} to obtain one.
+    /// Fluent builder for [Struct] dtypes. Use [#structBuilder()] to obtain one.
     /// Preserves insertion order and rejects duplicate field names at {@link #build()}.
     final class StructBuilder {
         private final LinkedHashMap<String, DType> fields = new LinkedHashMap<>();
@@ -193,7 +193,7 @@ public StructBuilder asNullable() {
             return this;
         }
 
-        /// Builds the {@link Struct} dtype.
+        /// Builds the [Struct] dtype.
         ///
         /// @return a new {@link Struct} reflecting every field added so far
         public Struct build() {
@@ -218,7 +218,7 @@ record Null(boolean nullable) implements DType {
     record Bool(boolean nullable) implements DType {
     }
 
-    /// Primitive numeric logical type backed by a physical {@link PType}.
+    /// Primitive numeric logical type backed by a physical [PType].
     ///
     /// @param ptype    physical primitive type (e.g. I32, F64)
     /// @param nullable whether null values are permitted
@@ -258,7 +258,7 @@ record Struct(
         /// Returns the type of the field with the given name.
         ///
         /// @param name the field name to look up
-        /// @return the {@link DType} of the named field
+        /// @return the [DType] of the named field
         /// @throws IllegalArgumentException if no field with that name exists
         public DType field(String name) {
             int i = fieldNames.indexOf(name);
@@ -304,7 +304,7 @@ record Extension(
         public static final int MAX_METADATA_SIZE = 64 * 1024;
 
         /// @throws VortexException if `metadata` carries more than
-        ///         {@link #MAX_METADATA_SIZE} readable bytes
+        ///         [#MAX_METADATA_SIZE] readable bytes
         public Extension {
             if (metadata != null && metadata.remaining() > MAX_METADATA_SIZE) {
                 throw new VortexException("extension metadata too large: "
diff --git a/core/src/main/java/io/github/dfa1/vortex/core/PType.java b/core/src/main/java/io/github/dfa1/vortex/core/PType.java
index 6ef35a57..85033fb9 100644
--- a/core/src/main/java/io/github/dfa1/vortex/core/PType.java
+++ b/core/src/main/java/io/github/dfa1/vortex/core/PType.java
@@ -56,7 +56,7 @@ public boolean isSigned() {
                        || this == F16 || this == F32 || this == F64;
     }
 
-    /// Returns the {@link PType} for the given enum ordinal — the integer value the wire format
+    /// Returns the [PType] for the given enum ordinal — the integer value the wire format
     /// uses to identify a physical type.
     ///
     /// Unlike `PType.values()[ordinal]`, this method validates the ordinal against the
diff --git a/core/src/main/java/io/github/dfa1/vortex/core/VortexException.java b/core/src/main/java/io/github/dfa1/vortex/core/VortexException.java
index 21172e4c..5f385f8c 100644
--- a/core/src/main/java/io/github/dfa1/vortex/core/VortexException.java
+++ b/core/src/main/java/io/github/dfa1/vortex/core/VortexException.java
@@ -11,7 +11,7 @@
 /// do not retry on the same input. The correct response is to abort the read, surface the error,
 /// and close the `VortexFile`.
 ///
-/// Carries an optional {@link EncodingId} for diagnostic attribution; it is not intended
+/// Carries an optional [EncodingId] for diagnostic attribution; it is not intended
 /// for recovery logic.
 public final class VortexException extends RuntimeException {
 
@@ -60,7 +60,7 @@ private static String prefix(EncodingId encodingId) {
 
     /// Returns the encoding that raised this exception, if known.
     ///
-    /// @return an {@link Optional} containing the {@link EncodingId}, or empty if not attributed
+    /// @return an [Optional] containing the [EncodingId], or empty if not attributed
     public Optional<EncodingId> encodingId() {
         return Optional.ofNullable(encodingId);
     }
diff --git a/core/src/main/java/io/github/dfa1/vortex/encoding/TimeUnit.java b/core/src/main/java/io/github/dfa1/vortex/encoding/TimeUnit.java
index 0efe85e9..e615cc27 100644
--- a/core/src/main/java/io/github/dfa1/vortex/encoding/TimeUnit.java
+++ b/core/src/main/java/io/github/dfa1/vortex/encoding/TimeUnit.java
@@ -27,7 +27,7 @@ public static TimeUnit fromTag(byte tag) {
     }
 
     /// Returns the number of this time unit's divisions in one second (e.g. 1_000_000_000 for nanoseconds).
-    /// Throws {@link IllegalArgumentException} for {@link #Days}.
+    /// Throws [IllegalArgumentException] for [#Days].
     ///
     /// @return divisor for converting between this unit and seconds
     public long divisor() {
diff --git a/core/src/main/java/io/github/dfa1/vortex/proto/ProtoReader.java b/core/src/main/java/io/github/dfa1/vortex/proto/ProtoReader.java
index c2cfa88b..eaf08eff 100644
--- a/core/src/main/java/io/github/dfa1/vortex/proto/ProtoReader.java
+++ b/core/src/main/java/io/github/dfa1/vortex/proto/ProtoReader.java
@@ -5,7 +5,7 @@
 import java.lang.foreign.ValueLayout;
 import java.nio.charset.StandardCharsets;
 
-/// Stateful cursor over a {@link MemorySegment} that decodes proto3 wire-format primitives.
+/// Stateful cursor over a [MemorySegment] that decodes proto3 wire-format primitives.
 /// Generated record types call into this from their {@code decode(...)} static factories.
 /// Package-private — generated code lives in the same package.
 final class ProtoReader {
@@ -35,13 +35,13 @@ long position() {
         return pos;
     }
 
-    /// Reads an unsigned varint into an {@code int}. Up to 5 bytes.
+    /// Reads an unsigned varint into an `int`. Up to 5 bytes.
     int readVarint32() throws IOException {
         long v = readVarint64();
         return (int) v;
     }
 
-    /// Reads an unsigned varint into a {@code long}. Up to 10 bytes.
+    /// Reads an unsigned varint into a `long`. Up to 10 bytes.
     long readVarint64() throws IOException {
         long result = 0;
         int shift = 0;
@@ -59,7 +59,7 @@ long readVarint64() throws IOException {
         throw new IOException("varint overflow at " + pos);
     }
 
-    /// Reads a zigzag-encoded signed varint into a {@code long}.
+    /// Reads a zigzag-encoded signed varint into a `long`.
     long readSint64() throws IOException {
         long n = readVarint64();
         return (n >>> 1) ^ -(n & 1);
@@ -107,7 +107,7 @@ String readString() throws IOException {
         return new String(bytes, StandardCharsets.UTF_8);
     }
 
-    /// Reads a length-delimited byte sequence into a fresh {@code byte[]}.
+    /// Reads a length-delimited byte sequence into a fresh `byte[]`.
     /// Use {@link #readLenDelimSegment()} for zero-copy access when the consumer can hold a segment slice.
     byte[] readBytes() throws IOException {
         int len = readVarint32();
@@ -155,7 +155,7 @@ void skipField(int wireType) throws IOException {
         }
     }
 
-    /// Consumes a packed-repeated payload, invoking {@code consumer.accept(this)} for each element.
+    /// Consumes a packed-repeated payload, invoking `consumer.accept(this)` for each element.
     /// The cursor advances over each element; loop ends when the packed region is exhausted.
     void readPacked(int len, PackedElementReader consumer) throws IOException {
         long packedEnd = pos + len;
diff --git a/core/src/main/java/io/github/dfa1/vortex/proto/ProtoWriter.java b/core/src/main/java/io/github/dfa1/vortex/proto/ProtoWriter.java
index 4eb7756f..4bbc4e92 100644
--- a/core/src/main/java/io/github/dfa1/vortex/proto/ProtoWriter.java
+++ b/core/src/main/java/io/github/dfa1/vortex/proto/ProtoWriter.java
@@ -4,7 +4,7 @@
 import java.util.Arrays;
 
 /// Growing-buffer writer for proto3 wire-format payloads.
-/// Generated record types call into this from their {@code encode()} methods.
+/// Generated record types call into this from their `encode()` methods.
 /// Package-private — generated code lives in the same package.
 final class ProtoWriter {
 
@@ -92,7 +92,7 @@ void writeEmbedded(byte[] encoded) {
     }
 
     /// Reserves space for a length-delimited region whose payload size is unknown until written.
-    /// Returns a mark to pass back to {@link #endLenDelim(int)}; the caller writes the payload
+    /// Returns a mark to pass back to [#endLenDelim(int)]; the caller writes the payload
     /// in between. Avoids the alloc/copy round-trip of writing into a temporary {@code ProtoWriter}.
     ///
     /// Reserves the worst-case 5 bytes for a varint32 length; {@link #endLenDelim} backpatches
@@ -104,7 +104,7 @@ int beginLenDelim() {
         return mark;
     }
 
-    /// Finalises a length-delimited region opened by {@link #beginLenDelim()}.
+    /// Finalises a length-delimited region opened by [#beginLenDelim()].
     /// Writes the payload length as a varint at the reserved offset and shifts the payload
     /// left if the varint is shorter than 5 bytes.
     void endLenDelim(int mark) {
diff --git a/core/src/main/java/io/github/dfa1/vortex/proto/WireType.java b/core/src/main/java/io/github/dfa1/vortex/proto/WireType.java
index c404efb2..020ae263 100644
--- a/core/src/main/java/io/github/dfa1/vortex/proto/WireType.java
+++ b/core/src/main/java/io/github/dfa1/vortex/proto/WireType.java
@@ -1,7 +1,7 @@
 package io.github.dfa1.vortex.proto;
 
 /// Proto3 wire-type constants.
-/// Each field on the wire is preceded by a tag varint encoding {@code (fieldNumber << 3) | wireType}.
+/// Each field on the wire is preceded by a tag varint encoding `(fieldNumber << 3) | wireType`.
 final class WireType {
 
     static final int VARINT = 0;
diff --git a/csv/src/main/java/io/github/dfa1/vortex/csv/CsvImporter.java b/csv/src/main/java/io/github/dfa1/vortex/csv/CsvImporter.java
index 27420c61..247a7499 100644
--- a/csv/src/main/java/io/github/dfa1/vortex/csv/CsvImporter.java
+++ b/csv/src/main/java/io/github/dfa1/vortex/csv/CsvImporter.java
@@ -159,14 +159,14 @@ private static void probeCell(boolean[] canBeLong, boolean[] canBeDouble, boolea
         if (canBeLong[c]) {
             try {
                 Long.parseLong(val);
-            } catch (NumberFormatException e) {
+            } catch (NumberFormatException _) {
                 canBeLong[c] = false;
             }
         }
         if (canBeDouble[c]) {
             try {
                 Double.parseDouble(val);
-            } catch (NumberFormatException e) {
+            } catch (NumberFormatException _) {
                 canBeDouble[c] = false;
             }
         }
diff --git a/inspector/src/main/java/io/github/dfa1/vortex/inspect/InspectorTree.java b/inspector/src/main/java/io/github/dfa1/vortex/inspect/InspectorTree.java
index 766fe129..a37ff937 100644
--- a/inspector/src/main/java/io/github/dfa1/vortex/inspect/InspectorTree.java
+++ b/inspector/src/main/java/io/github/dfa1/vortex/inspect/InspectorTree.java
@@ -83,7 +83,7 @@ public static InspectorTree build(VortexHandle handle) {
     }
 
     /// Builds an inspector tree without peeking segments — every node starts
-    /// with an empty encoding set and {@link ArrayStats#empty()} stats. The
+    /// with an empty encoding set and [ArrayStats#empty()] stats. The
     /// resulting tree contains only structure derived from the file's footer
     /// and layout, so the call is essentially free on remote handles.
     ///
@@ -132,7 +132,7 @@ private static Node shallowNode(Layout layout, Optional<String> fieldName) {
     /// compression, or missing data.
     ///
     /// Callers should cache the result — every call triggers a fresh
-    /// {@link io.github.dfa1.vortex.reader.VortexHandle#rawSegment}, which is a network round-trip on remote handles.
+    /// [io.github.dfa1.vortex.reader.VortexHandle#rawSegment], which is a network round-trip on remote handles.
     ///
     /// @param node   node to resolve
     /// @param handle open file handle
@@ -272,7 +272,7 @@ private static Peek peekFlatRoot(MemorySegment seg, List<String> arraySpecs) {
     /// statistics decoded from the same FlatBuffer.
     ///
     /// @param encoding resolved encoding id from the array spec table, or `null`
-    /// @param stats    per-array stats, or {@link ArrayStats#empty()} if unknown
+    /// @param stats    per-array stats, or [ArrayStats#empty()] if unknown
     public record Peek(String encoding, ArrayStats stats) {
         /// Sentinel returned for non-Flat nodes, compressed segments, or
         /// segments that don't carry an array root.
diff --git a/inspector/src/main/java/io/github/dfa1/vortex/inspect/ZonedStatsSchema.java b/inspector/src/main/java/io/github/dfa1/vortex/inspect/ZonedStatsSchema.java
index b973f1dc..6a9435e0 100644
--- a/inspector/src/main/java/io/github/dfa1/vortex/inspect/ZonedStatsSchema.java
+++ b/inspector/src/main/java/io/github/dfa1/vortex/inspect/ZonedStatsSchema.java
@@ -7,7 +7,7 @@
 import java.util.ArrayList;
 import java.util.List;
 
-/// Reconstructs the per-zone statistics-table {@link DType} for a
+/// Reconstructs the per-zone statistics-table [DType] for a
 /// `vortex.stats` (Zoned) layout.
 ///
 /// The shape is sourced from the Rust reference implementation:
@@ -31,7 +31,7 @@
 /// the inspector degrades to "no schema" rather than failing.
 public final class ZonedStatsSchema {
 
-    /// Ordinal positions of {@link Stat} in the Rust enum — kept stable across
+    /// Ordinal positions of [Stat] in the Rust enum — kept stable across
     /// Vortex versions so the bitset can be decoded without per-version logic.
     public enum Stat {
         /// Stat ordinal 0.
@@ -53,9 +53,9 @@ public enum Stat {
         /// Stat ordinal 8.
         NAN_COUNT("nan_count");
 
-        /// Trailing struct-field name added next to {@link #MAX} for truncated max indicators.
+        /// Trailing struct-field name added next to [#MAX] for truncated max indicators.
         public static final String MAX_IS_TRUNCATED = "max_is_truncated";
-        /// Trailing struct-field name added next to {@link #MIN} for truncated min indicators.
+        /// Trailing struct-field name added next to [#MIN] for truncated min indicators.
         public static final String MIN_IS_TRUNCATED = "min_is_truncated";
 
         private final String fieldName;
@@ -90,7 +90,7 @@ public static long zoneLength(ByteBuffer metadata) {
 
     /// Returns the stats present in the layout metadata bitset, in ordinal order.
     ///
-    /// Unknown bits (set at an index past {@link Stat#values()}'s length, which
+    /// Unknown bits (set at an index past [Stat#values()]'s length, which
     /// would mean a newer Vortex writer) are silently skipped — matching the Rust
     /// reader's forward-compatibility behaviour.
     ///
@@ -120,7 +120,7 @@ public static List<Stat> presentStats(ByteBuffer metadata) {
     /// Reconstructs the per-zone stats-table dtype for the given column dtype
     /// and metadata.
     ///
-    /// The result is a {@link io.github.dfa1.vortex.core.DType.Struct} mirroring
+    /// The result is a [io.github.dfa1.vortex.core.DType.Struct] mirroring
     /// the order produced by Rust's `stats_table_dtype`: for every present stat
     /// in ordinal order, append a `(name, nullable dtype)` field; Max/Min each
     /// add a trailing `_is_truncated` Bool (non-nullable) flag.
diff --git a/integration/src/test/java/io/github/dfa1/vortex/integration/ParquetImportIntegrationTest.java b/integration/src/test/java/io/github/dfa1/vortex/integration/ParquetImportIntegrationTest.java
index d62bf4ba..3b46c815 100644
--- a/integration/src/test/java/io/github/dfa1/vortex/integration/ParquetImportIntegrationTest.java
+++ b/integration/src/test/java/io/github/dfa1/vortex/integration/ParquetImportIntegrationTest.java
@@ -83,7 +83,7 @@ private static Path download(Path tmp, String name) throws Exception {
     private static void assumeNetworkAvailable() {
         try {
             URI.create("https://raw.githubusercontent.com").toURL().openStream().close();
-        } catch (Exception e) {
+        } catch (Exception _) {
             assumeTrue(false, "no network");
         }
     }
diff --git a/integration/src/test/java/io/github/dfa1/vortex/integration/PcoFixtureInspectionIntegrationTest.java b/integration/src/test/java/io/github/dfa1/vortex/integration/PcoFixtureInspectionIntegrationTest.java
index dbe948f0..9ebafb80 100644
--- a/integration/src/test/java/io/github/dfa1/vortex/integration/PcoFixtureInspectionIntegrationTest.java
+++ b/integration/src/test/java/io/github/dfa1/vortex/integration/PcoFixtureInspectionIntegrationTest.java
@@ -318,7 +318,7 @@ private static Path downloadIfMissing(Path tmp, String name) throws Exception {
     private static void assumeNetworkAvailable() {
         try {
             URI.create("https://vortex-compat-fixtures.s3.amazonaws.com").toURL().openStream().close();
-        } catch (Exception e) {
+        } catch (Exception _) {
             assumeTrue(false, "no network");
         }
     }
diff --git a/integration/src/test/java/io/github/dfa1/vortex/integration/RustJavaReaderComparisonIntegrationTest.java b/integration/src/test/java/io/github/dfa1/vortex/integration/RustJavaReaderComparisonIntegrationTest.java
index 7c48cd33..e0c0a9c2 100644
--- a/integration/src/test/java/io/github/dfa1/vortex/integration/RustJavaReaderComparisonIntegrationTest.java
+++ b/integration/src/test/java/io/github/dfa1/vortex/integration/RustJavaReaderComparisonIntegrationTest.java
@@ -52,7 +52,7 @@
 
 /// Cross-decoder correctness: downloads each S3 fixture once, then compares row counts,
 /// numeric column sums, and string byte-length sums from the Rust reader and the
-/// Java {@link VortexReader}.
+/// Java [VortexReader].
 ///
 /// Both readers decode the same local bytes — no auth, no network dependency during
 /// decode. A mismatch in any column value points to a decoding bug in the Java reader.
diff --git a/integration/src/test/java/io/github/dfa1/vortex/integration/RustWritesJavaReadsIntegrationTest.java b/integration/src/test/java/io/github/dfa1/vortex/integration/RustWritesJavaReadsIntegrationTest.java
index 4b99a424..c63dff90 100644
--- a/integration/src/test/java/io/github/dfa1/vortex/integration/RustWritesJavaReadsIntegrationTest.java
+++ b/integration/src/test/java/io/github/dfa1/vortex/integration/RustWritesJavaReadsIntegrationTest.java
@@ -219,7 +219,7 @@ private static Path downloadIfMissing(Path tmp, String name) throws Exception {
     private static void assumeNetworkAvailable() {
         try {
             URI.create("https://vortex-compat-fixtures.s3.amazonaws.com").toURL().openStream().close();
-        } catch (Exception e) {
+        } catch (Exception _) {
             assumeTrue(false, "no network");
         }
     }
diff --git a/jdbc/src/main/java/io/github/dfa1/vortex/jdbc/JdbcImportOptions.java b/jdbc/src/main/java/io/github/dfa1/vortex/jdbc/JdbcImportOptions.java
index 736e438b..8ae3fa64 100644
--- a/jdbc/src/main/java/io/github/dfa1/vortex/jdbc/JdbcImportOptions.java
+++ b/jdbc/src/main/java/io/github/dfa1/vortex/jdbc/JdbcImportOptions.java
@@ -6,7 +6,7 @@
 ///
 /// @param fetchSize        number of rows the JDBC driver fetches per round-trip
 /// @param chunkSize        number of rows per Vortex chunk written to disk
-/// @param writeOptions     encoding and compression settings passed to {@link io.github.dfa1.vortex.writer.VortexWriter}
+/// @param writeOptions     encoding and compression settings passed to [io.github.dfa1.vortex.writer.VortexWriter]
 /// @param progressListener optional callback invoked after each full chunk is written; `null` disables progress reporting
 public record JdbcImportOptions(
         int fetchSize,
diff --git a/jdbc/src/main/java/io/github/dfa1/vortex/jdbc/JdbcImporter.java b/jdbc/src/main/java/io/github/dfa1/vortex/jdbc/JdbcImporter.java
index e6dd9303..1195bede 100644
--- a/jdbc/src/main/java/io/github/dfa1/vortex/jdbc/JdbcImporter.java
+++ b/jdbc/src/main/java/io/github/dfa1/vortex/jdbc/JdbcImporter.java
@@ -25,7 +25,7 @@
 import java.util.Map;
 import java.util.UUID;
 
-/// Reads rows from a JDBC {@link ResultSet} and writes a Vortex file.
+/// Reads rows from a JDBC [ResultSet] and writes a Vortex file.
 ///
 /// The schema is derived from {@link ResultSetMetaData} — no type inference is needed.
 /// SQL NULL values are mapped to `0`, `0.0`, `false`, or `""` depending on column type.
diff --git a/jdbc/src/test/java/io/github/dfa1/vortex/jdbc/JdbcImporterTest.java b/jdbc/src/test/java/io/github/dfa1/vortex/jdbc/JdbcImporterTest.java
index 5a5728d1..04abf1c5 100644
--- a/jdbc/src/test/java/io/github/dfa1/vortex/jdbc/JdbcImporterTest.java
+++ b/jdbc/src/test/java/io/github/dfa1/vortex/jdbc/JdbcImporterTest.java
@@ -360,7 +360,7 @@ void nullValuesPreserveValidityViaMaskedArray(@TempDir Path tmp) throws Exceptio
                         assertThat(nMasked.isValid(1)).isTrue();
                         assertThat(nMasked.isValid(2)).isTrue();
                         LongArray nInner = (LongArray) nMasked.inner();
-                        assertThat(nInner.getLong(1)).isEqualTo(0L);
+                        assertThat(nInner.getLong(1)).isZero();
                         assertThat(nInner.getLong(2)).isEqualTo(42L);
 
                         io.github.dfa1.vortex.reader.array.MaskedArray sMasked =
diff --git a/parquet/src/main/java/io/github/dfa1/vortex/parquet/ParquetImporter.java b/parquet/src/main/java/io/github/dfa1/vortex/parquet/ParquetImporter.java
index 4a4384f9..57de76a8 100644
--- a/parquet/src/main/java/io/github/dfa1/vortex/parquet/ParquetImporter.java
+++ b/parquet/src/main/java/io/github/dfa1/vortex/parquet/ParquetImporter.java
@@ -41,7 +41,7 @@
 /// - BYTE_ARRAY annotated STRING, ENUM, or JSON → Utf8
 ///
 /// All other physical types (INT96, FIXED_LEN_BYTE_ARRAY, unannotated BYTE_ARRAY, DECIMAL,
-/// DATE, TIME, TIMESTAMP) throw {@link UnsupportedOperationException}.
+/// DATE, TIME, TIMESTAMP) throw [UnsupportedOperationException].
 public final class ParquetImporter {
 
     private ParquetImporter() {
diff --git a/proto-gen/src/main/java/io/github/dfa1/vortex/protogen/Ast.java b/proto-gen/src/main/java/io/github/dfa1/vortex/protogen/Ast.java
index 30b1bf6d..12f845be 100644
--- a/proto-gen/src/main/java/io/github/dfa1/vortex/protogen/Ast.java
+++ b/proto-gen/src/main/java/io/github/dfa1/vortex/protogen/Ast.java
@@ -30,7 +30,7 @@ public sealed interface TopDecl permits MessageDecl, EnumDecl {
     public record MessageDecl(String name, List<MessageMember> members) implements TopDecl, MessageMember {
     }
 
-    /// A member of a {@link MessageDecl}.
+    /// A member of a [MessageDecl].
     public sealed interface MessageMember permits FieldDecl, OneOfDecl, MessageDecl, EnumDecl {
     }
 
diff --git a/proto-gen/src/main/java/io/github/dfa1/vortex/protogen/CodeGen.java b/proto-gen/src/main/java/io/github/dfa1/vortex/protogen/CodeGen.java
index 75741d3d..a7ff06a7 100644
--- a/proto-gen/src/main/java/io/github/dfa1/vortex/protogen/CodeGen.java
+++ b/proto-gen/src/main/java/io/github/dfa1/vortex/protogen/CodeGen.java
@@ -6,7 +6,7 @@
 import java.util.ArrayList;
 import java.util.List;
 
-/// Walks a {@link TypeRegistry} and emits one `.java` file per message or enum.
+/// Walks a [TypeRegistry] and emits one `.java` file per message or enum.
 ///
 /// Output:
 /// - Each enum becomes a Java `enum` with bounds-checked `fromValue(int)`.
@@ -588,7 +588,7 @@ private static String writeStmtOnWriter(Ast.Scalar s, String writer, String valu
     // Enum emitters (wire type = VARINT)
     // ------------------------------------------------------------------
 
-    /// Emits a try/catch wrapper that translates {@link IllegalArgumentException} from
+    /// Emits a try/catch wrapper that translates [IllegalArgumentException] from
     /// `Enum.fromValue(int)` into a checked {@link IOException}. The caller must already be
     /// inside a `throws IOException` context (every `decode(...)` factory is).
     private static void emitEnumDecodeWrap(StringBuilder sb, String indent, String javaName, String assignTarget) {
diff --git a/proto-gen/src/main/java/io/github/dfa1/vortex/protogen/Lexer.java b/proto-gen/src/main/java/io/github/dfa1/vortex/protogen/Lexer.java
index dc230475..da4c3e1d 100644
--- a/proto-gen/src/main/java/io/github/dfa1/vortex/protogen/Lexer.java
+++ b/proto-gen/src/main/java/io/github/dfa1/vortex/protogen/Lexer.java
@@ -3,7 +3,7 @@
 import java.util.ArrayList;
 import java.util.List;
 
-/// Tokenizes a proto3 source file into a list of {@link Token}s.
+/// Tokenizes a proto3 source file into a list of [Token]s.
 /// Comments (`//` line, `/* ... */` block) and whitespace are dropped.
 public final class Lexer {
 
diff --git a/proto-gen/src/main/java/io/github/dfa1/vortex/protogen/Parser.java b/proto-gen/src/main/java/io/github/dfa1/vortex/protogen/Parser.java
index 3d3a6be5..3b01b198 100644
--- a/proto-gen/src/main/java/io/github/dfa1/vortex/protogen/Parser.java
+++ b/proto-gen/src/main/java/io/github/dfa1/vortex/protogen/Parser.java
@@ -15,7 +15,7 @@ public final class Parser {
     private final List<Token> tokens;
     private int pos;
 
-    /// @param tokens token stream produced by {@link Lexer}
+    /// @param tokens token stream produced by [Lexer]
     public Parser(List<Token> tokens) {
         this.tokens = tokens;
         this.pos = 0;
diff --git a/proto-gen/src/main/java/io/github/dfa1/vortex/protogen/Token.java b/proto-gen/src/main/java/io/github/dfa1/vortex/protogen/Token.java
index f5e72355..bbc12617 100644
--- a/proto-gen/src/main/java/io/github/dfa1/vortex/protogen/Token.java
+++ b/proto-gen/src/main/java/io/github/dfa1/vortex/protogen/Token.java
@@ -1,6 +1,6 @@
 package io.github.dfa1.vortex.protogen;
 
-/// A token emitted by {@link Lexer}.
+/// A token emitted by [Lexer].
 ///
 /// @param kind  token kind
 /// @param text  source text — meaningful for {@link Kind#IDENT}, {@link Kind#INT_LITERAL}, {@link Kind#STRING_LITERAL}
diff --git a/proto-gen/src/main/java/io/github/dfa1/vortex/protogen/TypeRegistry.java b/proto-gen/src/main/java/io/github/dfa1/vortex/protogen/TypeRegistry.java
index 962bd66d..db2e39a3 100644
--- a/proto-gen/src/main/java/io/github/dfa1/vortex/protogen/TypeRegistry.java
+++ b/proto-gen/src/main/java/io/github/dfa1/vortex/protogen/TypeRegistry.java
@@ -71,7 +71,7 @@ private void indexNested(Ast.MessageDecl parent, String parentFqn, String javaPa
         }
     }
 
-    /// Resolves a textual {@link Ast.Ref#typeName()} to its concrete type, searching first
+    /// Resolves a textual [Ast.Ref#typeName()] to its concrete type, searching first
     /// for an exact qualified match, then attempting to match under `searchPackage`
     /// (the package of the file containing the reference).
     ///
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/ArrayStats.java b/reader/src/main/java/io/github/dfa1/vortex/reader/ArrayStats.java
index 34ff602a..e8816354 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/ArrayStats.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/ArrayStats.java
@@ -28,12 +28,12 @@ public record ArrayStats(
 
     /// Returns an empty stats instance with all fields set to `null`.
     ///
-    /// @return an empty {@link ArrayStats} with no known statistics
+    /// @return an empty [ArrayStats] with no known statistics
     public static ArrayStats empty() {
         return EMPTY;
     }
 
-    /// Parses stats from a FlatBuffers {@link io.github.dfa1.vortex.fbs.ArrayStats} table.
+    /// Parses stats from a FlatBuffers [io.github.dfa1.vortex.fbs.ArrayStats] table.
     /// Returns an empty instance when `fbs` is `null` or carries no min/max.
     ///
     /// @param fbs the FlatBuffers stats table, or `null`
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/Chunk.java b/reader/src/main/java/io/github/dfa1/vortex/reader/Chunk.java
index d4c19467..6788a135 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/Chunk.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/Chunk.java
@@ -102,7 +102,7 @@ public <T extends Array> T column(String name) {
     /// this accessor is closed over the spec set.
     ///
     /// @param name       column name as declared in the file's schema
-    /// @param domainType the spec extension's Java domain type (e.g. {@link LocalDate} for
+    /// @param domainType the spec extension's Java domain type (e.g. [LocalDate] for
     ///                   `vortex.date`, {@link Instant} for `vortex.timestamp`)
     /// @param <T>        domain element type
     /// @return decoded values in row order
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/CompressionScheme.java b/reader/src/main/java/io/github/dfa1/vortex/reader/CompressionScheme.java
index 0a65ed49..30817b68 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/CompressionScheme.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/CompressionScheme.java
@@ -21,7 +21,7 @@ public enum CompressionScheme {
     /// Returns the enum constant matching the given numeric code.
     ///
     /// @param code numeric compression code from the file postscript
-    /// @return the matching {@link CompressionScheme}
+    /// @return the matching [CompressionScheme]
     /// @throws IllegalArgumentException if `code` does not correspond to any known scheme
     public static CompressionScheme of(int code) {
         return switch (code) {
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/ExtensionDecoder.java b/reader/src/main/java/io/github/dfa1/vortex/reader/ExtensionDecoder.java
index 44317a61..d43ff82f 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/ExtensionDecoder.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/ExtensionDecoder.java
@@ -5,7 +5,7 @@
 
 /// Read-side contract for a Vortex extension type.
 ///
-/// Implementations pair a spec identity ({@link ExtensionId}) with the matching
+/// Implementations pair a spec identity ([ExtensionId]) with the matching
 /// {@link DType.Extension} dtype. Typed decode methods live on each concrete
 /// implementation — they are not on this interface, so read callers get typed return
 /// values without casting through `Object`.
@@ -15,6 +15,6 @@ public interface ExtensionDecoder {
     ExtensionId extensionId();
 
     /// @param nullable whether the column allows nulls
-    /// @return matching {@link DType.Extension} (storage dtype + default metadata)
+    /// @return matching [DType.Extension] (storage dtype + default metadata)
     DType.Extension dtype(boolean nullable);
 }
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/FlatSegmentDecoder.java b/reader/src/main/java/io/github/dfa1/vortex/reader/FlatSegmentDecoder.java
index 13272e07..1c764adf 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/FlatSegmentDecoder.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/FlatSegmentDecoder.java
@@ -16,7 +16,7 @@
 import java.util.List;
 
 /// Parses a flat segment from the memory-mapped file region and dispatches to the
-/// appropriate decoder via the {@link ReadRegistry}.
+/// appropriate decoder via the [ReadRegistry].
 ///
 /// Flat segment wire format:
 /// `buffer_data... | FlatBuffer(Array) | u32 LE = FlatBuffer byte length`
@@ -41,7 +41,7 @@ public FlatSegmentDecoder(ReadRegistry registry) {
     /// @param dtype         expected logical type for the decoded array
     /// @param rowCount      number of logical rows in this segment
     /// @param arena         allocator for decode output; lifetime matches the current chunk epoch
-    /// @return the decoded {@link Array} for this segment
+    /// @return the decoded [Array] for this segment
     public Array decode(MemorySegment seg, List<String> encodingSpecs,
             DType dtype, long rowCount, SegmentAllocator arena) {
         int segLen = (int) seg.byteSize();
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/Layout.java b/reader/src/main/java/io/github/dfa1/vortex/reader/Layout.java
index 3cb5dc99..d87fead3 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/Layout.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/Layout.java
@@ -35,35 +35,35 @@ public record Layout(
 
     /// Returns `true` if this layout is a flat (leaf) layout.
     ///
-    /// @return `true` when `encodingId` equals {@link #FLAT}
+    /// @return `true` when `encodingId` equals [#FLAT]
     public boolean isFlat() {
         return FLAT.equals(encodingId);
     }
 
     /// Returns `true` if this layout is a chunked layout.
     ///
-    /// @return `true` when `encodingId` equals {@link #CHUNKED}
+    /// @return `true` when `encodingId` equals [#CHUNKED]
     public boolean isChunked() {
         return CHUNKED.equals(encodingId);
     }
 
     /// Returns `true` if this layout is a struct layout.
     ///
-    /// @return `true` when `encodingId` equals {@link #STRUCT}
+    /// @return `true` when `encodingId` equals [#STRUCT]
     public boolean isStruct() {
         return STRUCT.equals(encodingId);
     }
 
     /// Returns `true` if this layout is a zone-map (stats) layout.
     ///
-    /// @return `true` when `encodingId` equals {@link #ZONED}
+    /// @return `true` when `encodingId` equals [#ZONED]
     public boolean isZoned() {
         return ZONED.equals(encodingId);
     }
 
     /// Returns `true` if this layout is a dictionary layout.
     ///
-    /// @return `true` when `encodingId` equals {@link #DICT}
+    /// @return `true` when `encodingId` equals [#DICT]
     public boolean isDict() {
         return DICT.equals(encodingId);
     }
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/PostscriptParser.java b/reader/src/main/java/io/github/dfa1/vortex/reader/PostscriptParser.java
index 4fcf470c..79d5f31d 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/PostscriptParser.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/PostscriptParser.java
@@ -26,7 +26,7 @@ final class PostscriptParser {
     /// Hard cap on layout-tree recursion depth. Real-world layouts are typically four levels
     /// (Struct → Zoned → Chunked → Flat); 64 is well past any expected schema and prevents
     /// adversarial inputs — deeply nested trees or self-referential FlatBuffer cycles — from
-    /// blowing the JVM stack during {@link #convertLayout(io.github.dfa1.vortex.fbs.Layout, List, int)}.
+    /// blowing the JVM stack during [#convertLayout(io.github.dfa1.vortex.fbs.Layout, List, int)].
     static final int MAX_LAYOUT_DEPTH = 64;
 
     /// Hard cap on per-layout metadata size. The FlatBuffer runtime returns an unbounded slice
@@ -68,7 +68,7 @@ static ParsedFile parse(ByteBuffer postscriptBuf, MemorySegment fileSegment, lon
         return parsed;
     }
 
-    /// Rejects {@link SegmentSpec} entries whose declared range is not entirely contained in the
+    /// Rejects [SegmentSpec] entries whose declared range is not entirely contained in the
     /// memory-mapped file. Without this check, every scan-time `fileSegment.asSlice(offset,
     /// length)` on these specs would throw [IndexOutOfBoundsException], breaking the
     /// "malformed input → [VortexException]" contract.
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/ReadRegistry.java b/reader/src/main/java/io/github/dfa1/vortex/reader/ReadRegistry.java
index 95b2cd88..29a4f71d 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/ReadRegistry.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/ReadRegistry.java
@@ -16,7 +16,7 @@
 import java.util.Map;
 import java.util.ServiceLoader;
 
-/// Read-side registry: maps {@link EncodingId} to {@link EncodingDecoder} implementations.
+/// Read-side registry: maps [EncodingId] to [EncodingDecoder] implementations.
 ///
 /// Instances are immutable after construction. Build one via {@link #builder()} or
 /// via the {@link #loadAll()} and {@link #empty()} convenience factories.
@@ -30,7 +30,7 @@ private ReadRegistry(Map<EncodingId, EncodingDecoder> decoders, boolean allowUnk
         this.allowUnknown = allowUnknown;
     }
 
-    /// Loads all service-discovered {@link EncodingDecoder} implementations.
+    /// Loads all service-discovered [EncodingDecoder] implementations.
     ///
     /// @return an immutable {@link ReadRegistry} populated with all service-loaded decoders
     public static ReadRegistry loadAll() {
@@ -39,12 +39,12 @@ public static ReadRegistry loadAll() {
 
     /// Creates an empty registry with no decoders registered.
     ///
-    /// @return a new empty immutable {@link ReadRegistry}
+    /// @return a new empty immutable [ReadRegistry]
     public static ReadRegistry empty() {
         return builder().build();
     }
 
-    /// Returns a new {@link Builder}.
+    /// Returns a new [Builder].
     ///
     /// @return a fresh builder
     public static Builder builder() {
@@ -54,7 +54,7 @@ public static Builder builder() {
     /// Returns whether passthrough decode for unknown encoding ids is enabled.
     ///
     /// @return `true` if unknown encodings are silently wrapped as
-    ///         {@link io.github.dfa1.vortex.reader.array.UnknownArray}
+    ///         [io.github.dfa1.vortex.reader.array.UnknownArray]
     public boolean isAllowUnknown() {
         return allowUnknown;
     }
@@ -70,7 +70,7 @@ public boolean hasDecoder(EncodingId encodingId) {
     /// Decodes the array described by `ctx`.
     ///
     /// @param ctx the decode context
-    /// @return the decoded {@link Array}
+    /// @return the decoded [Array]
     public Array decode(DecodeContext ctx) {
         ArrayNode node = ctx.node();
         EncodingDecoder decoder = switch (node) {
@@ -93,7 +93,7 @@ public Array decode(DecodeContext ctx) {
     /// Decodes the array described by `ctx` and returns its primary backing segment.
     ///
     /// @param ctx the decode context
-    /// @return the primary {@link MemorySegment} of the decoded array
+    /// @return the primary [MemorySegment] of the decoded array
     public MemorySegment decodeAsSegment(DecodeContext ctx) {
         ArrayNode node = ctx.node();
         EncodingDecoder decoder = switch (node) {
@@ -132,7 +132,7 @@ private static UnknownArray decodeUnknown(DecodeContext ctx, ArrayNode node) {
                 node.metadata(), bufs, children);
     }
 
-    /// Builder for {@link ReadRegistry}.
+    /// Builder for [ReadRegistry].
     ///
     /// Not thread-safe. Build once, use everywhere — the produced {@link ReadRegistry} is immutable.
     public static final class Builder {
@@ -145,7 +145,7 @@ private Builder() {
 
         /// Registers a decoder.
         ///
-        /// @param decoder the {@link EncodingDecoder} to register
+        /// @param decoder the [EncodingDecoder] to register
         /// @return this builder, for chaining
         /// @throws VortexException if a decoder for the same id is already registered
         public Builder register(EncodingDecoder decoder) {
@@ -156,7 +156,7 @@ public Builder register(EncodingDecoder decoder) {
             return this;
         }
 
-        /// Registers every {@link EncodingDecoder} discovered via {@link ServiceLoader}.
+        /// Registers every [EncodingDecoder] discovered via [ServiceLoader].
         ///
         /// @return this builder, for chaining
         /// @throws VortexException if a service-loaded entry collides with one already registered
@@ -169,7 +169,7 @@ public Builder registerServiceLoaded() {
 
         /// Enable passthrough decode for unknown encoding ids.
         ///
-        /// Default is strict: unknown ids throw {@link VortexException}. When enabled, unknown
+        /// Default is strict: unknown ids throw [VortexException]. When enabled, unknown
         /// nodes are wrapped as {@link io.github.dfa1.vortex.reader.array.UnknownArray}.
         /// Mirrors Rust `VortexSession::allow_unknown()`.
         ///
@@ -179,7 +179,7 @@ public Builder allowUnknown() {
             return this;
         }
 
-        /// Builds an immutable {@link ReadRegistry}.
+        /// Builds an immutable [ReadRegistry].
         ///
         /// @return the immutable registry
         public ReadRegistry build() {
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/ScanIterator.java b/reader/src/main/java/io/github/dfa1/vortex/reader/ScanIterator.java
index 89bf6239..c0195029 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/ScanIterator.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/ScanIterator.java
@@ -187,7 +187,7 @@ private static ChunkSpec buildChunkSpec(String[] colNames, Map<String, List<Layo
     private static int compareValues(Object a, Object b) {
         try {
             return ((Comparable<Object>) a).compareTo(b);
-        } catch (ClassCastException e) {
+        } catch (ClassCastException _) {
             return 0;
         }
     }
@@ -654,7 +654,7 @@ private static void validateDictCodesCapacity(Array codes, PType codesPType, lon
     }
 
     /// Builds the matching `DictXxxArray` for a primitive dictionary, unwrapping
-    /// any {@link MaskedArray} layer on either side — dictionary lookups are keyed by code
+    /// any [MaskedArray] layer on either side — dictionary lookups are keyed by code
     /// so value-side validity is meaningless at this layer.
     ///
     /// @param dtype  primitive logical type of dict values
@@ -752,7 +752,7 @@ private boolean canPruneChunk(ChunkSpec chunk, RowFilter filter) {
                     @SuppressWarnings("unchecked")
                     Comparable<Object> cv = (Comparable<Object>) val;
                     yield cv.compareTo(min) < 0 || cv.compareTo(max) > 0;
-                } catch (ClassCastException e) {
+                } catch (ClassCastException _) {
                     yield false;
                 }
             }
@@ -771,7 +771,7 @@ private boolean canPruneChunk(ChunkSpec chunk, RowFilter filter) {
                     @SuppressWarnings("unchecked")
                     Comparable<Object> cv = (Comparable<Object>) val;
                     yield cv.compareTo(min) == 0 && cv.compareTo(max) == 0;
-                } catch (ClassCastException e) {
+                } catch (ClassCastException _) {
                     yield false;
                 }
             }
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/VortexHandle.java b/reader/src/main/java/io/github/dfa1/vortex/reader/VortexHandle.java
index bfbb5347..15ae5958 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/VortexHandle.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/VortexHandle.java
@@ -22,7 +22,7 @@ public interface VortexHandle extends Closeable {
 
     long fileSize();
 
-    /// Typed accessor for the common pattern "read a flat segment by its {@link SegmentSpec}
+    /// Typed accessor for the common pattern "read a flat segment by its [SegmentSpec]
     /// and decode the encoded array contained therein."
     ///
     /// @param spec     the segment spec to read from
@@ -39,13 +39,13 @@ public interface VortexHandle extends Closeable {
     /// On HTTP handles this fires a targeted range request.
     ///
     /// @param spec the segment to read
-    /// @return a read-only {@link MemorySegment} covering exactly `spec.offset()` to
+    /// @return a read-only [MemorySegment] covering exactly `spec.offset()` to
     ///         `spec.offset() + spec.length()`
     MemorySegment rawSegment(SegmentSpec spec);
 
     ScanIterator scan(ScanOptions options);
 
-    /// Returns the {@link ReadRegistry} this handle was opened with.
+    /// Returns the [ReadRegistry] this handle was opened with.
     ///
     /// **Internal escape hatch.** Exposed for tooling
     /// (e.g. the inspector's dictionary preview) that needs to decode an
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/VortexHttpReader.java b/reader/src/main/java/io/github/dfa1/vortex/reader/VortexHttpReader.java
index d518c058..f8bab8ec 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/VortexHttpReader.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/VortexHttpReader.java
@@ -68,7 +68,7 @@ public static VortexHttpReader open(URI uri, ReadRegistry registry) throws IOExc
         return open(uri, registry, CLIENT);
     }
 
-    /// Opens a remote Vortex file using a caller-supplied {@link HttpClient}.
+    /// Opens a remote Vortex file using a caller-supplied [HttpClient].
     ///
     /// Use this overload when the default shared client is unsuitable — e.g. to configure
     /// a proxy, custom TLS context, or per-request timeout.
@@ -256,7 +256,7 @@ public io.github.dfa1.vortex.reader.array.Array decodeFlatSegment(
     }
 
     /// Fetches the bytes of the given segment spec via HTTP Range.
-    /// Returns an off-heap {@link MemorySegment} tied to this reader's {@link Arena}.
+    /// Returns an off-heap [MemorySegment] tied to this reader's [Arena].
     ///
     /// @param spec the segment to fetch
     /// @return a read-only {@link MemorySegment} containing the fetched bytes
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/ArraySegments.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/ArraySegments.java
index 3348d486..ea71e6f5 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/array/ArraySegments.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/array/ArraySegments.java
@@ -7,7 +7,7 @@
 import java.lang.foreign.SegmentAllocator;
 import java.util.Optional;
 
-/// Internal materialization engine: turns any {@link Array} into its primary
+/// Internal materialization engine: turns any [Array] into its primary
 /// {@link MemorySegment}, allocating from a caller-supplied arena for lazy variants.
 ///
 /// If `arr` is a {@link MaskedArray}, the inner (data) segment is returned;
@@ -64,7 +64,7 @@ private static MemorySegment primarySegment(Array arr) {
     /// fresh segment allocated from `arena`.
     ///
     /// Use this overload when the caller already holds a chunk-scoped allocator (e.g.
-    /// {@link io.github.dfa1.vortex.reader.ReadRegistry#decodeAsSegment}) so lazy array types
+    /// [io.github.dfa1.vortex.reader.ReadRegistry#decodeAsSegment]) so lazy array types
     /// do not need to carry the arena as a record component.
     ///
     /// @param arr   the array whose segment is needed
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/BooleanConsumer.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/BooleanConsumer.java
index c1bea724..2a42d1ba 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/array/BooleanConsumer.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/array/BooleanConsumer.java
@@ -1,6 +1,6 @@
 package io.github.dfa1.vortex.reader.array;
 
-/// Consumer of `boolean` values. Used by {@link BoolArray#forEachBoolean(BooleanConsumer)}.
+/// Consumer of `boolean` values. Used by [BoolArray#forEachBoolean(BooleanConsumer)].
 @FunctionalInterface
 public interface BooleanConsumer {
 
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/ByteConsumer.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/ByteConsumer.java
index 2c98a2f7..f486a3b5 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/array/ByteConsumer.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/array/ByteConsumer.java
@@ -1,6 +1,6 @@
 package io.github.dfa1.vortex.reader.array;
 
-/// Consumer of `byte` values. Used by {@link ByteArray#forEachByte(ByteConsumer)}.
+/// Consumer of `byte` values. Used by [ByteArray#forEachByte(ByteConsumer)].
 @FunctionalInterface
 public interface ByteConsumer {
 
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedBoolArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedBoolArray.java
index 7594c591..87cde5dc 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedBoolArray.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedBoolArray.java
@@ -7,7 +7,7 @@
 import java.util.Collections;
 import java.util.List;
 
-/// Multi-chunk {@link BoolArray} record. ADR 0012 shape.
+/// Multi-chunk [BoolArray] record. ADR 0012 shape.
 ///
 /// Bit-packed boolean columns store one bit per row across the children's
 /// segments; this record dispatches each scalar read to the chunk that
@@ -20,7 +20,7 @@
 @SuppressWarnings("java:S6218") // internal data carrier; record components are arrays of immutable primitives or refs that flow through pipelines without ever being compared.
 public record ChunkedBoolArray(DType dtype, long length, BoolArray[] children, long[] offsets) implements BoolArray {
 
-    /// Builds a {@link ChunkedBoolArray}.
+    /// Builds a [ChunkedBoolArray].
     ///
     /// @param dtype     logical element type
     /// @param totalRows expected total row count
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedByteArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedByteArray.java
index b1f5a04d..744c3f6f 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedByteArray.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedByteArray.java
@@ -8,7 +8,7 @@
 import java.util.List;
 import java.util.function.LongBinaryOperator;
 
-/// Multi-chunk {@link ByteArray} record. ADR 0012 shape.
+/// Multi-chunk [ByteArray] record. ADR 0012 shape.
 ///
 /// @param dtype    logical element type (I8 or U8)
 /// @param length   total logical row count
@@ -17,7 +17,7 @@
 @SuppressWarnings("java:S6218") // internal data carrier; record components are arrays of immutable primitives or refs that flow through pipelines without ever being compared.
 public record ChunkedByteArray(DType dtype, long length, ByteArray[] children, long[] offsets) implements ByteArray {
 
-    /// Builds a {@link ChunkedByteArray}.
+    /// Builds a [ChunkedByteArray].
     ///
     /// @param dtype     logical element type
     /// @param totalRows expected total row count
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedDoubleArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedDoubleArray.java
index 8ef1bb19..67a05ca6 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedDoubleArray.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedDoubleArray.java
@@ -9,7 +9,7 @@
 import java.util.function.DoubleBinaryOperator;
 import java.util.function.DoubleConsumer;
 
-/// Multi-chunk {@link DoubleArray} view; record per ADR 0012 with stateless
+/// Multi-chunk [DoubleArray] view; record per ADR 0012 with stateless
 /// {@link ChunkedLongArray#findChunk(long[], long)} dispatch.
 ///
 /// @param dtype    logical element type
@@ -19,7 +19,7 @@
 @SuppressWarnings("java:S6218") // internal data carrier; record components are arrays of immutable primitives or refs that flow through pipelines without ever being compared.
 public record ChunkedDoubleArray(DType dtype, long length, DoubleArray[] children, long[] offsets) implements DoubleArray {
 
-    /// Builds a {@link ChunkedDoubleArray}. Flattens nested chunked arrays;
+    /// Builds a [ChunkedDoubleArray]. Flattens nested chunked arrays;
     /// unwraps {@link MaskedArray} chunks.
     ///
     /// @param dtype     logical element type
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedFloatArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedFloatArray.java
index 57774403..518591ba 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedFloatArray.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedFloatArray.java
@@ -8,7 +8,7 @@
 import java.util.List;
 import java.util.function.DoubleBinaryOperator;
 
-/// Multi-chunk {@link FloatArray} record. ADR 0012 shape.
+/// Multi-chunk [FloatArray] record. ADR 0012 shape.
 ///
 /// @param dtype    logical element type
 /// @param length   total logical row count
@@ -17,7 +17,7 @@
 @SuppressWarnings("java:S6218") // internal data carrier; record components are arrays of immutable primitives or refs that flow through pipelines without ever being compared.
 public record ChunkedFloatArray(DType dtype, long length, FloatArray[] children, long[] offsets) implements FloatArray {
 
-    /// Builds a {@link ChunkedFloatArray}.
+    /// Builds a [ChunkedFloatArray].
     ///
     /// @param dtype     logical element type
     /// @param totalRows expected total row count
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedIntArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedIntArray.java
index 0541285c..43bee57e 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedIntArray.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedIntArray.java
@@ -9,7 +9,7 @@
 import java.util.function.IntBinaryOperator;
 import java.util.function.IntConsumer;
 
-/// Multi-chunk {@link IntArray} record. ADR 0012 shape.
+/// Multi-chunk [IntArray] record. ADR 0012 shape.
 ///
 /// @param dtype    logical element type
 /// @param length   total logical row count
@@ -18,7 +18,7 @@
 @SuppressWarnings("java:S6218") // internal data carrier; record components are arrays of immutable primitives or refs that flow through pipelines without ever being compared.
 public record ChunkedIntArray(DType dtype, long length, IntArray[] children, long[] offsets) implements IntArray {
 
-    /// Builds a {@link ChunkedIntArray}.
+    /// Builds a [ChunkedIntArray].
     ///
     /// @param dtype     logical element type
     /// @param totalRows expected total row count
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedLongArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedLongArray.java
index dd7dcd61..cfc1ffb7 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedLongArray.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedLongArray.java
@@ -10,7 +10,7 @@
 import java.util.function.LongBinaryOperator;
 import java.util.function.LongConsumer;
 
-/// Multi-chunk {@link LongArray} view backed by an immutable array of child
+/// Multi-chunk [LongArray] view backed by an immutable array of child
 /// chunks plus their cumulative row offsets. Scalar access is stateless —
 /// {@link #getLong(long)} resolves the chunk index via {@link #findChunk(long[], long)}
 /// (a binary search over `offsets`) on every call.
@@ -27,7 +27,7 @@
 @SuppressWarnings("java:S6218") // internal data carrier; record components are arrays of immutable primitives or refs that flow through pipelines without ever being compared.
 public record ChunkedLongArray(DType dtype, long length, LongArray[] children, long[] offsets) implements LongArray {
 
-    /// Builds a {@link ChunkedLongArray} from a list of chunk arrays. Nested
+    /// Builds a [ChunkedLongArray] from a list of chunk arrays. Nested
     /// chunked arrays are flattened; {@link MaskedArray} chunks are unwrapped
     /// to their inner data (validity dropped — matches prior concat behaviour).
     ///
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedShortArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedShortArray.java
index 200ba172..841e690f 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedShortArray.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedShortArray.java
@@ -8,7 +8,7 @@
 import java.util.List;
 import java.util.function.LongBinaryOperator;
 
-/// Multi-chunk {@link ShortArray} record. ADR 0012 shape — children hold their
+/// Multi-chunk [ShortArray] record. ADR 0012 shape — children hold their
 /// own segments; scalar access binary-searches `offsets`.
 ///
 /// @param dtype    logical element type (I16 or U16)
@@ -18,7 +18,7 @@
 @SuppressWarnings("java:S6218") // internal data carrier; record components are arrays of immutable primitives or refs that flow through pipelines without ever being compared.
 public record ChunkedShortArray(DType dtype, long length, ShortArray[] children, long[] offsets) implements ShortArray {
 
-    /// Builds a {@link ChunkedShortArray}.
+    /// Builds a [ChunkedShortArray].
     ///
     /// @param dtype     logical element type
     /// @param totalRows expected total row count
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/DateTimePartsArrays.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/DateTimePartsArrays.java
index 79933d96..2d46ecba 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/array/DateTimePartsArrays.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/array/DateTimePartsArrays.java
@@ -2,7 +2,7 @@
 
 import io.github.dfa1.vortex.core.VortexException;
 
-/// Package-private helper for the {@link LazyDateTimePartsLongArray} record.
+/// Package-private helper for the [LazyDateTimePartsLongArray] record.
 ///
 /// `days`, `seconds` and `subseconds` children can each be one of
 /// the four signed-integer typed array interfaces; the writer picks the narrowest
@@ -13,7 +13,7 @@ final class DateTimePartsArrays {
     private DateTimePartsArrays() {
     }
 
-    /// Reads `arr[i]` as a signed long. Recurses through {@link MaskedArray};
+    /// Reads `arr[i]` as a signed long. Recurses through [MaskedArray];
     /// throws on null cells so callers don't silently get garbage for nullable
     /// columns.
     ///
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/DecimalBytePartsArrays.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/DecimalBytePartsArrays.java
index 7229ed84..f4eddd96 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/array/DecimalBytePartsArrays.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/array/DecimalBytePartsArrays.java
@@ -4,7 +4,7 @@
 
 import java.math.BigInteger;
 
-/// Package-private helper for the {@link LazyDecimalBytePartsArray} record.
+/// Package-private helper for the [LazyDecimalBytePartsArray] record.
 ///
 /// `vortex.decimal_byte_parts` with `lower_part_count == 0` stores the
 /// decimal mantissa as a single signed-integer child column whose ptype the
@@ -16,7 +16,7 @@ final class DecimalBytePartsArrays {
     private DecimalBytePartsArrays() {
     }
 
-    /// Reads `arr[i]` as a signed-magnitude {@link BigInteger} mantissa.
+    /// Reads `arr[i]` as a signed-magnitude [BigInteger] mantissa.
     /// Recurses through {@link MaskedArray}; throws on null cells so callers
     /// don't silently get a zero mantissa for invalid rows.
     ///
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/DictDoubleArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/DictDoubleArray.java
index 131a60af..942f7f78 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/array/DictDoubleArray.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/array/DictDoubleArray.java
@@ -6,7 +6,7 @@
 import java.util.function.DoubleBinaryOperator;
 import java.util.function.DoubleConsumer;
 
-/// Dict-encoded {@link DoubleArray} view. ADR 0012 shape.
+/// Dict-encoded [DoubleArray] view. ADR 0012 shape.
 ///
 /// Stores `values` (the dictionary pool) and `codes` (one index per
 /// row into `values`). Scalar access resolves on demand:
@@ -24,7 +24,7 @@
 ///               {@link ByteArray}, {@link ShortArray}, {@link IntArray}, {@link LongArray}
 public record DictDoubleArray(DType dtype, long length, DoubleArray values, Array codes) implements DoubleArray {
 
-    /// Builds a {@link DictDoubleArray}, validating that `codes` is one of the
+    /// Builds a [DictDoubleArray], validating that `codes` is one of the
     /// four narrow-int code array types and that its length matches `length`.
     ///
     /// @param dtype  logical element type
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/DictFloatArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/DictFloatArray.java
index 245d5fea..8ac59b42 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/array/DictFloatArray.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/array/DictFloatArray.java
@@ -5,7 +5,7 @@
 
 import java.util.function.DoubleBinaryOperator;
 
-/// Dict-encoded {@link FloatArray} view. ADR 0012 shape.
+/// Dict-encoded [FloatArray] view. ADR 0012 shape.
 ///
 /// Stores `values` (the dictionary pool) and `codes` (one index per
 /// row into `values`). Scalar access resolves on demand:
@@ -23,7 +23,7 @@
 ///               {@link ByteArray}, {@link ShortArray}, {@link IntArray}, {@link LongArray}
 public record DictFloatArray(DType dtype, long length, FloatArray values, Array codes) implements FloatArray {
 
-    /// Builds a {@link DictFloatArray}, validating that `codes` is one of the
+    /// Builds a [DictFloatArray], validating that `codes` is one of the
     /// four narrow-int code array types and that its length matches `length`.
     ///
     /// @param dtype  logical element type
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/DictIntArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/DictIntArray.java
index 1e9085e6..c463c89f 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/array/DictIntArray.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/array/DictIntArray.java
@@ -6,7 +6,7 @@
 import java.util.function.IntBinaryOperator;
 import java.util.function.IntConsumer;
 
-/// Dict-encoded {@link IntArray} view. ADR 0012 shape.
+/// Dict-encoded [IntArray] view. ADR 0012 shape.
 ///
 /// Stores `values` (the dictionary pool) and `codes` (one index per
 /// row into `values`). Scalar access resolves on demand:
@@ -24,7 +24,7 @@
 ///               {@link ByteArray}, {@link ShortArray}, {@link IntArray}, {@link LongArray}
 public record DictIntArray(DType dtype, long length, IntArray values, Array codes) implements IntArray {
 
-    /// Builds a {@link DictIntArray}, validating that `codes` is one of the
+    /// Builds a [DictIntArray], validating that `codes` is one of the
     /// four narrow-int code array types and that its length matches `length`.
     ///
     /// @param dtype  logical element type
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/DictLongArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/DictLongArray.java
index c36cd7ae..8f015948 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/array/DictLongArray.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/array/DictLongArray.java
@@ -6,7 +6,7 @@
 import java.util.function.LongBinaryOperator;
 import java.util.function.LongConsumer;
 
-/// Dict-encoded {@link LongArray} view. ADR 0012 shape.
+/// Dict-encoded [LongArray] view. ADR 0012 shape.
 ///
 /// Stores `values` (the dictionary pool) and `codes` (one index per
 /// row into `values`). Scalar access resolves on demand:
@@ -27,7 +27,7 @@
 ///               {@link ByteArray}, {@link ShortArray}, {@link IntArray}, {@link LongArray}
 public record DictLongArray(DType dtype, long length, LongArray values, Array codes) implements LongArray {
 
-    /// Builds a {@link DictLongArray}, validating that `codes` is one of the
+    /// Builds a [DictLongArray], validating that `codes` is one of the
     /// four narrow-int code array types and that its length matches `length`.
     ///
     /// @param dtype  logical element type
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/FixedSizeListArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/FixedSizeListArray.java
index 5bd94738..f771836d 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/array/FixedSizeListArray.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/array/FixedSizeListArray.java
@@ -49,7 +49,7 @@ public int fixedSize() {
     /// Returns the elements child array.
     ///
     /// @param i must be 0
-    /// @return the child {@link Array} at index `i`
+    /// @return the child [Array] at index `i`
     public Array child(int i) {
         if (i != 0) {
             throw new ArrayIndexOutOfBoundsException("FixedSizeListArray child index " + i);
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/Float16Array.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/Float16Array.java
index fc6d08e9..f3a79901 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/array/Float16Array.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/array/Float16Array.java
@@ -4,7 +4,7 @@
 /// [Array] for F16 (IEEE 754 half-precision) columns.
 ///
 /// Wire format: little-endian shorts (2 bytes/element). Element access widens
-/// to `float` via {@link Float#float16ToFloat}. The default impl is
+/// to `float` via [Float#float16ToFloat]. The default impl is
 /// [MaterializedFloat16Array], a buffer-backed record returned when an
 /// encoding decoder either materialises values eagerly or has no lazy
 /// variant of its own.
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/GenericArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/GenericArray.java
index 63b4d09f..462df9d5 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/array/GenericArray.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/array/GenericArray.java
@@ -55,7 +55,7 @@ public long length() {
 
     /// Returns a view of this array clamped to the first `rows` logical rows.
     /// Buffers and children are reused as-is; callers are expected to respect
-    /// {@link #length()} when reading. Used by the scan iterator to honour
+    /// [#length()] when reading. Used by the scan iterator to honour
     /// `ScanOptions.limit` for dtypes that don't have a typed array.
     ///
     /// @param rows desired logical length; must be `<= length()`
@@ -80,7 +80,7 @@ MemorySegment buffer(int i) {
     /// Decodes the decimal value at row `i` from a single-buffer layout.
     ///
     /// The buffer holds one little-endian two's-complement integer per row. Element
-    /// width is derived from the buffer's byte size divided by {@link #length()},
+    /// width is derived from the buffer's byte size divided by [#length()],
     /// not from the dtype's precision — `vortex.decimal` writes whatever width
     /// the encoder chose in its `valuesType` metadata, which can be narrower
     /// than the precision alone would allow.
@@ -154,7 +154,7 @@ private static BigInteger readSigned128Le(MemorySegment buf, long offset) {
     /// Returns the child array at position `i`.
     ///
     /// @param i child index
-    /// @return the child {@link Array} at index `i`
+    /// @return the child [Array] at index `i`
     public Array child(int i) {
         return children[i];
     }
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyAlpDoubleArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyAlpDoubleArray.java
index 3f181436..beb252d3 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyAlpDoubleArray.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyAlpDoubleArray.java
@@ -12,7 +12,7 @@
 /// mirrors the Rust reference (`ALPFloat::decode_single`) — pre-multiplying the two factors
 /// into a single `scale` gives different IEEE rounding for non-trivial `expF`,
 /// breaking round-trip with the encoder's verify step.
-/// Returned by {@link io.github.dfa1.vortex.reader.decode.AlpEncodingDecoder} when the chunk has
+/// Returned by [io.github.dfa1.vortex.reader.decode.AlpEncodingDecoder] when the chunk has
 /// no patches and the source is not a broadcast constant; patched or broadcast chunks fall back
 /// to [MaterializedDoubleArray].
 ///
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyConstantBoolArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyConstantBoolArray.java
index 7a37c0af..3b3b68db 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyConstantBoolArray.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyConstantBoolArray.java
@@ -9,7 +9,7 @@
 /// for any valid index, replacing the `(n+7)/8`-byte `0xFF`-fill the
 /// buffer-backed path required.
 ///
-/// @param dtype  logical {@link DType.Bool} type
+/// @param dtype  logical [DType.Bool] type
 /// @param length total logical row count
 /// @param value  broadcast value
 public record LazyConstantBoolArray(DType dtype, long length, boolean value) implements BoolArray {
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyDateTimePartsLongArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyDateTimePartsLongArray.java
index e9b9b8b1..813255c8 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyDateTimePartsLongArray.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyDateTimePartsLongArray.java
@@ -5,7 +5,7 @@
 import java.util.function.LongBinaryOperator;
 import java.util.function.LongConsumer;
 
-/// Lazy `vortex.datetimeparts` reassembly as a {@link LongArray}.
+/// Lazy `vortex.datetimeparts` reassembly as a [LongArray].
 ///
 /// The encoding splits each raw epoch count into three children — `days`,
 /// `seconds` (within the day) and `subseconds` (within the second).
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyDecimalArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyDecimalArray.java
index 1cc61f97..e7894e7d 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyDecimalArray.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyDecimalArray.java
@@ -14,7 +14,7 @@
 /// `vortex.decimal` stores one little-endian two's-complement integer per row;
 /// the integer's byte width (1/2/4/8/16) is fixed for the whole array and chosen
 /// by the writer based on precision. The buffer is a mmap slice — decode wraps
-/// it; per-row {@link #getDecimal(long)} reads `byteWidth` bytes and combines
+/// it; per-row [#getDecimal(long)] reads `byteWidth` bytes and combines
 /// them with the parent dtype's scale into a {@link BigDecimal} on demand. No
 /// arena allocation happens at construction time.
 ///
@@ -31,7 +31,7 @@ public record LazyDecimalArray(DType dtype, long length, MemorySegment buf, int
     private static final ValueLayout.OfLong LONG_LE =
             ValueLayout.JAVA_LONG_UNALIGNED.withOrder(ByteOrder.LITTLE_ENDIAN);
 
-    /// Reads cell `i` as a {@link BigDecimal} with the parent dtype's scale.
+    /// Reads cell `i` as a [BigDecimal] with the parent dtype's scale.
     ///
     /// @param i row index, `0 <= i < length()`
     /// @return decoded `BigDecimal`
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyDecimalBytePartsArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyDecimalBytePartsArray.java
index a8ff4c88..ac09b629 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyDecimalBytePartsArray.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyDecimalBytePartsArray.java
@@ -9,7 +9,7 @@
 ///
 /// With `lower_part_count == 0` (the only shape this codebase currently
 /// emits or accepts) the encoding stores its mantissa as a single signed-integer
-/// child column, paired with the parent's {@link DType.Decimal} precision and
+/// child column, paired with the parent's [DType.Decimal] precision and
 /// scale. {@link #getDecimal(long)} reads one cell from the child via
 /// {@link DecimalBytePartsArrays#readMantissa(Array, long)} and combines it with
 /// the dtype scale to produce a {@link BigDecimal} on demand — no buffer
@@ -20,7 +20,7 @@
 /// @param msp    child array holding the most-significant integer part of the mantissa
 public record LazyDecimalBytePartsArray(DType dtype, long length, Array msp) implements DecimalArray {
 
-    /// Reads cell `i` as a {@link BigDecimal} with the parent dtype's scale.
+    /// Reads cell `i` as a [BigDecimal] with the parent dtype's scale.
     ///
     /// @param i row index, `0 <= i < length()`
     /// @return decoded `BigDecimal`
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyForIntArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyForIntArray.java
index 744be12b..c902183c 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyForIntArray.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyForIntArray.java
@@ -8,7 +8,7 @@
 /// Lazy [IntArray] backed by the `fastlanes.for` encoded `i32` child segment.
 ///
 /// Decode is deferred to element access: `getInt(i) = encoded[i] + ref`.
-/// Returned by {@link io.github.dfa1.vortex.reader.decode.FrameOfReferenceEncodingDecoder} when
+/// Returned by [io.github.dfa1.vortex.reader.decode.FrameOfReferenceEncodingDecoder] when
 /// `ref != 0` and the source is not a broadcast constant.
 ///
 /// @param dtype   logical I32/U32 type
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyForLongArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyForLongArray.java
index 76abe560..0b9538a2 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyForLongArray.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyForLongArray.java
@@ -8,7 +8,7 @@
 /// Lazy [LongArray] backed by the `fastlanes.for` encoded `i64` child segment.
 ///
 /// Decode is deferred to element access: `getLong(i) = encoded[i] + ref`.
-/// Returned by {@link io.github.dfa1.vortex.reader.decode.FrameOfReferenceEncodingDecoder} when
+/// Returned by [io.github.dfa1.vortex.reader.decode.FrameOfReferenceEncodingDecoder] when
 /// `ref != 0` and the source is not a broadcast constant.
 ///
 /// @param dtype   logical I64/U64 type
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyZigZagIntArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyZigZagIntArray.java
index a91262b7..1fcfe41f 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyZigZagIntArray.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyZigZagIntArray.java
@@ -8,7 +8,7 @@
 /// Lazy [IntArray] backed by the `vortex.zigzag` encoded `u32` child segment.
 ///
 /// Decode is deferred to element access: `getInt(i) = (u >>> 1) ^ -(u & 1)`.
-/// Returned by {@link io.github.dfa1.vortex.reader.decode.ZigZagEncodingDecoder} when the source
+/// Returned by [io.github.dfa1.vortex.reader.decode.ZigZagEncodingDecoder] when the source
 /// is not a broadcast constant.
 ///
 /// @param dtype   logical I32 type
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyZigZagLongArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyZigZagLongArray.java
index 2d96232c..1508239b 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyZigZagLongArray.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/array/LazyZigZagLongArray.java
@@ -8,7 +8,7 @@
 /// Lazy [LongArray] backed by the `vortex.zigzag` encoded `u64` child segment.
 ///
 /// Decode is deferred to element access: `getLong(i) = (u >>> 1) ^ -(u & 1)`.
-/// Returned by {@link io.github.dfa1.vortex.reader.decode.ZigZagEncodingDecoder} when the source
+/// Returned by [io.github.dfa1.vortex.reader.decode.ZigZagEncodingDecoder] when the source
 /// is not a broadcast constant.
 ///
 /// @param dtype   logical I64 type
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/ListArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/ListArray.java
index 71a72a67..4cb4d04b 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/array/ListArray.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/array/ListArray.java
@@ -54,7 +54,7 @@ public Array offsets() {
     /// Returns the child array at position `i` (0 = elements, 1 = offsets).
     ///
     /// @param i child index
-    /// @return the child {@link Array}
+    /// @return the child [Array]
     public Array child(int i) {
         return switch (i) {
             case 0 -> elements;
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/ListViewArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/ListViewArray.java
index 737ab5ad..b61a10f3 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/array/ListViewArray.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/array/ListViewArray.java
@@ -5,7 +5,7 @@
 
 /// Decoded variable-length list-view array (Arrow ListView layout).
 ///
-/// Unlike {@link ListArray}, offsets and sizes are independent per row:
+/// Unlike [ListArray], offsets and sizes are independent per row:
 /// `list[i] = elements[offsets[i] .. offsets[i] + sizes[i]]`.
 /// Both `offsets` and `sizes` have length `outerLen` (not outerLen+1).
 public final class ListViewArray implements Array {
@@ -65,7 +65,7 @@ public Array sizes() {
     /// Returns the child array at position `i` (0 = elements, 1 = offsets, 2 = sizes).
     ///
     /// @param i child index
-    /// @return the child {@link Array}
+    /// @return the child [Array]
     public Array child(int i) {
         return switch (i) {
             case 0 -> elements;
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/MaskedArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/MaskedArray.java
index bef9258a..5e2e452d 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/array/MaskedArray.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/array/MaskedArray.java
@@ -7,7 +7,7 @@
 /// Invariant: `child` has no actual nulls — nullability is expressed solely via
 /// `validity`. When `validity` is `null` all positions are valid.
 ///
-/// Use {@link #inner()} to access the payload and {@link #isValid(long)} to check validity
+/// Use [#inner()] to access the payload and [#isValid(long)] to check validity
 /// before trusting a value.
 public final class MaskedArray implements Array {
 
@@ -35,7 +35,7 @@ public long length() {
 
     /// Returns the non-nullable payload array wrapped by this masked array.
     ///
-    /// @return the inner payload {@link Array}
+    /// @return the inner payload [Array]
     public Array inner() {
         return child;
     }
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/MaterializedBoolArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/MaterializedBoolArray.java
index 0c908f26..882ffcf2 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/array/MaterializedBoolArray.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/array/MaterializedBoolArray.java
@@ -16,7 +16,7 @@ public final class MaterializedBoolArray implements BoolArray {
 
     /// Constructs a `MaterializedBoolArray` backed by the given bit-packed buffer.
     ///
-    /// @param dtype  logical type, must be {@link io.github.dfa1.vortex.core.DType.Bool}
+    /// @param dtype  logical type, must be [io.github.dfa1.vortex.core.DType.Bool]
     /// @param length number of logical boolean elements
     /// @param buffer bit-packed boolean data (LSB-first, one byte per 8 elements)
     public MaterializedBoolArray(DType dtype, long length, MemorySegment buffer) {
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/MaterializedByteArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/MaterializedByteArray.java
index 282f12cf..1500b66f 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/array/MaterializedByteArray.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/array/MaterializedByteArray.java
@@ -19,7 +19,7 @@ public final class MaterializedByteArray implements ByteArray {
 
     /// Constructs a `MaterializedByteArray` backed by the given buffer.
     ///
-    /// @param dtype  logical type, must be a {@link io.github.dfa1.vortex.core.DType.Primitive} with ptype I8 or U8
+    /// @param dtype  logical type, must be a [io.github.dfa1.vortex.core.DType.Primitive] with ptype I8 or U8
     /// @param length number of logical elements
     /// @param buffer raw byte data (one byte per element)
     public MaterializedByteArray(DType dtype, long length, MemorySegment buffer) {
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/MaterializedDoubleArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/MaterializedDoubleArray.java
index d1c12bcd..5ab40d0a 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/array/MaterializedDoubleArray.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/array/MaterializedDoubleArray.java
@@ -18,7 +18,7 @@ public final class MaterializedDoubleArray implements DoubleArray {
 
     /// Constructs a `MaterializedDoubleArray` backed by the given buffer.
     ///
-    /// @param dtype  logical type, must be a {@link io.github.dfa1.vortex.core.DType.Primitive} with ptype F64
+    /// @param dtype  logical type, must be a [io.github.dfa1.vortex.core.DType.Primitive] with ptype F64
     /// @param length number of logical elements
     /// @param buffer raw double data (8 bytes per element, little-endian)
     public MaterializedDoubleArray(DType dtype, long length, MemorySegment buffer) {
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/ShortConsumer.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/ShortConsumer.java
index b862ff30..8d81b352 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/array/ShortConsumer.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/array/ShortConsumer.java
@@ -2,7 +2,7 @@
 
 /// Consumer of `short` values. JDK has `IntConsumer` / `LongConsumer`
 /// but no narrow-primitive variants, so this fills the gap for
-/// {@link ShortArray#forEachShort(ShortConsumer)}.
+/// [ShortArray#forEachShort(ShortConsumer)].
 @FunctionalInterface
 public interface ShortConsumer {
 
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/UnknownArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/UnknownArray.java
index 3ed2fb00..680c7c56 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/array/UnknownArray.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/array/UnknownArray.java
@@ -34,7 +34,7 @@ public record UnknownArray(
     /// Returns the child array at position `i`.
     ///
     /// @param i child index
-    /// @return the child {@link Array} at index `i`
+    /// @return the child [Array] at index `i`
     public Array child(int i) {
         return children[i];
     }
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/VarBinArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/VarBinArray.java
index ef9a00cc..9e46dec6 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/array/VarBinArray.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/array/VarBinArray.java
@@ -75,7 +75,7 @@ public VarBinArray limited(long rows) {
 
     /// Returns the concatenated raw bytes segment backing all elements.
     ///
-    /// @return the bytes {@link MemorySegment}
+    /// @return the bytes [MemorySegment]
     MemorySegment bytesSegment();
 
     /// Returns a copy of the raw bytes for element `i`.
@@ -107,7 +107,7 @@ public VarBinArray limited(long rows) {
     /// @return a `VarBinArray` containing the first `rows` elements
     VarBinArray limited(long rows);
 
-    /// Materialises any `VarBinArray` into a flat {@link OffsetMode}. The fast path
+    /// Materialises any `VarBinArray` into a flat [OffsetMode]. The fast path
     /// returns `src` unchanged when it is already an {@link OffsetMode}. Other modes
     /// (ViewMode in particular) walk every row through the typed accessors, copy the bytes
     /// into a fresh contiguous segment allocated from `arena`, and build an I64
@@ -309,7 +309,7 @@ private long dictReadOff(long i) {
     /// owning chunk and delegate. Per ADR 0012, preserves zero-copy on multi-chunk Utf8 /
     /// Binary columns: each chunk's underlying segments stay live (mmap slices); no concat.
     ///
-    /// {@link #bytesSegment()} is the {@link MemorySegment#NULL} sentinel — chunked
+    /// [#bytesSegment()] is the [MemorySegment#NULL] sentinel — chunked
     /// arrays have no single contiguous bytes segment. Callers that need contiguous
     /// bytes must materialise via the chunked children.
     ///
@@ -325,7 +325,7 @@ record ChunkedMode(DType dtype, long length, VarBinArray[] children, long[] offs
         ///
         /// @param dtype     logical element type
         /// @param totalRows expected total row count
-        /// @param chunks    non-empty list of {@link VarBinArray} chunks
+        /// @param chunks    non-empty list of [VarBinArray] chunks
         /// @return a new `ChunkedMode`
         /// @throws VortexException on empty input, non-{@link VarBinArray} chunks, or row-count mismatch
         public static ChunkedMode of(DType dtype, long totalRows,
@@ -427,7 +427,7 @@ public VarBinArray limited(long rows) {
     /// buffer. Per-row accessors resolve the view on demand — no concat or
     /// materialisation at construction time.
     ///
-    /// {@link #bytesSegment()} returns {@link MemorySegment#NULL} because there is
+    /// [#bytesSegment()] returns [MemorySegment#NULL] because there is
     /// no single contiguous bytes segment; callers needing one must materialise via
     /// the typed accessors.
     ///
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/array/VariantArray.java b/reader/src/main/java/io/github/dfa1/vortex/reader/array/VariantArray.java
index 562a4919..a5fa605e 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/array/VariantArray.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/array/VariantArray.java
@@ -41,14 +41,14 @@ public long length() {
 
     /// Returns the core storage array holding the full variant value for every row.
     ///
-    /// @return core storage {@link Array}
+    /// @return core storage [Array]
     public Array coreStorage() {
         return coreStorage;
     }
 
     /// Returns the optional typed shredded array, or `null` if absent.
     ///
-    /// @return shredded {@link Array}, or `null`
+    /// @return shredded [Array], or `null`
     public Array shredded() {
         return shredded;
     }
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/AlpEncodingDecoder.java b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/AlpEncodingDecoder.java
index d37aa89a..8fb0399f 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/AlpEncodingDecoder.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/AlpEncodingDecoder.java
@@ -29,7 +29,7 @@ public final class AlpEncodingDecoder implements EncodingDecoder {
     private static final DType I64_DTYPE = new DType.Primitive(PType.I64, false);
     private static final DType I32_DTYPE = new DType.Primitive(PType.I32, false);
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public AlpEncodingDecoder() {
     }
 
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/AlpRdEncodingDecoder.java b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/AlpRdEncodingDecoder.java
index a2ada124..fa3006e9 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/AlpRdEncodingDecoder.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/AlpRdEncodingDecoder.java
@@ -25,7 +25,7 @@ public final class AlpRdEncodingDecoder implements EncodingDecoder {
     private static final DType U32_DTYPE = new DType.Primitive(PType.U32, false);
     private static final DType U64_DTYPE = new DType.Primitive(PType.U64, false);
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public AlpRdEncodingDecoder() {
     }
 
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/ArrayNode.java b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/ArrayNode.java
index be4e6185..2a023746 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/ArrayNode.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/ArrayNode.java
@@ -9,7 +9,7 @@
 ///
 /// Sealed: a node is either [KnownArrayNode] (id resolves to an [EncodingId]) or
 /// [UnknownArrayNode] (id is an arbitrary string only meaningful for
-/// {@link io.github.dfa1.vortex.reader.ReadRegistry#isAllowUnknown()} passthrough decode).
+/// [io.github.dfa1.vortex.reader.ReadRegistry#isAllowUnknown()] passthrough decode).
 public sealed interface ArrayNode permits KnownArrayNode, UnknownArrayNode {
 
     /// Short factory for the common case: a node whose encoding id is well-known.
@@ -20,7 +20,7 @@ public sealed interface ArrayNode permits KnownArrayNode, UnknownArrayNode {
     /// @param metadata      encoding-specific metadata bytes, or `null`
     /// @param children      child nodes
     /// @param bufferIndices segment buffer indices for this node
-    /// @return a {@link KnownArrayNode} with the given fields
+    /// @return a [KnownArrayNode] with the given fields
     static ArrayNode of(EncodingId encodingId, ByteBuffer metadata, ArrayNode[] children,
             int[] bufferIndices) {
         return new KnownArrayNode(encodingId, metadata, children, bufferIndices);
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/BitpackedEncodingDecoder.java b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/BitpackedEncodingDecoder.java
index d25c4819..f6ba10ea 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/BitpackedEncodingDecoder.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/BitpackedEncodingDecoder.java
@@ -22,7 +22,7 @@
 public final class BitpackedEncodingDecoder implements EncodingDecoder {
     private static final int[] FL_ORDER = {0, 4, 2, 6, 1, 5, 3, 7};
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public BitpackedEncodingDecoder() {
     }
 
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/BoolEncodingDecoder.java b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/BoolEncodingDecoder.java
index a43de0be..5aad4b5d 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/BoolEncodingDecoder.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/BoolEncodingDecoder.java
@@ -10,7 +10,7 @@
 /// Read-only decoder for bit-packed boolean arrays.
 public final class BoolEncodingDecoder implements EncodingDecoder {
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public BoolEncodingDecoder() {
     }
 
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/ByteBoolEncodingDecoder.java b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/ByteBoolEncodingDecoder.java
index 266c818b..b4331aef 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/ByteBoolEncodingDecoder.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/ByteBoolEncodingDecoder.java
@@ -9,10 +9,10 @@
 import java.lang.foreign.ValueLayout;
 
 /// Read-only decoder for `vortex.bytebool` — packs the input byte buffer into the
-/// bit-packed {@link BoolArray} layout used by `vortex.bool`.
+/// bit-packed [BoolArray] layout used by `vortex.bool`.
 public final class ByteBoolEncodingDecoder implements EncodingDecoder {
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public ByteBoolEncodingDecoder() {
     }
 
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/ChunkedEncodingDecoder.java b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/ChunkedEncodingDecoder.java
index 633b7977..9275381c 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/ChunkedEncodingDecoder.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/ChunkedEncodingDecoder.java
@@ -26,7 +26,7 @@ public final class ChunkedEncodingDecoder implements EncodingDecoder {
     private static final ValueLayout.OfLong LE_LONG =
             ValueLayout.JAVA_LONG_UNALIGNED.withOrder(ByteOrder.LITTLE_ENDIAN);
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public ChunkedEncodingDecoder() {
     }
 
@@ -74,7 +74,7 @@ private static long[] readOffsets(DecodeContext ctx, int nchunks) {
     }
 
     /// Wraps the decoded chunk children in a zero-copy view: a `ChunkedXxxArray`
-    /// for primitives and Bool, a {@link StructArray} of per-field chunked views for
+    /// for primitives and Bool, a [StructArray] of per-field chunked views for
     /// {@link DType.Struct}. No concat / no per-row materialise.
     private static Array wrap(List<Array> chunks, DType dtype, long totalRows) {
         if (dtype instanceof DType.Primitive pt) {
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/ConstantEncodingDecoder.java b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/ConstantEncodingDecoder.java
index 0bad922e..c96a3ac4 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/ConstantEncodingDecoder.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/ConstantEncodingDecoder.java
@@ -26,7 +26,7 @@
 /// Read-only decoder for `vortex.constant`.
 public final class ConstantEncodingDecoder implements EncodingDecoder {
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public ConstantEncodingDecoder() {
     }
 
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/DateTimePartsEncodingDecoder.java b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/DateTimePartsEncodingDecoder.java
index 8a58efb7..a34fa228 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/DateTimePartsEncodingDecoder.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/DateTimePartsEncodingDecoder.java
@@ -16,7 +16,7 @@
 /// Read-only decoder for `vortex.datetimeparts`.
 ///
 /// Reassembles the three children (days, seconds, subseconds) into a
-/// {@link LazyDateTimePartsLongArray} of epoch counts in the extension's
+/// [LazyDateTimePartsLongArray] of epoch counts in the extension's
 /// {@link TimeUnit}. No per-row materialisation happens at decode time —
 /// the downstream extension decoder reads the reassembled long via the
 /// lazy `getLong` accessor.
@@ -24,7 +24,7 @@ public final class DateTimePartsEncodingDecoder implements EncodingDecoder {
 
     private static final long SECONDS_PER_DAY = 86_400L;
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public DateTimePartsEncodingDecoder() {
     }
 
@@ -73,7 +73,7 @@ public Array decode(DecodeContext ctx) {
     }
 
     /// Returns `TimeUnit.divisor()` for the extension's declared time unit, or
-    /// `1` when the unit is {@link TimeUnit#Days} (days carry no sub-second
+    /// `1` when the unit is [TimeUnit#Days] (days carry no sub-second
     /// component; seconds and subseconds children are expected to be zero).
     private static long readUnitsPerSecond(DType.Extension ext) {
         ByteBuffer extMeta = ext.metadata();
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/DecimalBytePartsEncodingDecoder.java b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/DecimalBytePartsEncodingDecoder.java
index 187ec1f2..57b99c41 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/DecimalBytePartsEncodingDecoder.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/DecimalBytePartsEncodingDecoder.java
@@ -15,7 +15,7 @@
 /// Read-only decoder for `vortex.decimal_byte_parts`.
 public final class DecimalBytePartsEncodingDecoder implements EncodingDecoder {
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public DecimalBytePartsEncodingDecoder() {
     }
 
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/DecimalEncodingDecoder.java b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/DecimalEncodingDecoder.java
index 90c4651a..4d678492 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/DecimalEncodingDecoder.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/DecimalEncodingDecoder.java
@@ -14,7 +14,7 @@
 /// Read-only decoder for `vortex.decimal`.
 public final class DecimalEncodingDecoder implements EncodingDecoder {
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public DecimalEncodingDecoder() {
     }
 
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/DecodeContext.java b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/DecodeContext.java
index 3d0d3d05..cb822e52 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/DecodeContext.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/DecodeContext.java
@@ -9,7 +9,7 @@
 import java.lang.foreign.SegmentAllocator;
 import java.nio.ByteBuffer;
 
-/// Decoding context passed to each {@link EncodingDecoder}.
+/// Decoding context passed to each [EncodingDecoder].
 ///
 /// Buffers are {@link MemorySegment} slices materialized from the file's segment table;
 /// children are decoded recursively via {@link #decodeChild(int)}.
@@ -35,7 +35,7 @@ public record DecodeContext(
     /// Recursively decode child `i` using this context's dtype and row count.
     ///
     /// @param i zero-based child index within this node's children array
-    /// @return the decoded {@link Array} for child `i`
+    /// @return the decoded [Array] for child `i`
     public Array decodeChild(int i) {
         ArrayNode child = node.children()[i];
         var childCtx = new DecodeContext(child, dtype, rowCount, segmentBuffers, registry, arena);
@@ -50,7 +50,7 @@ public Array decodeChild(int i) {
     /// @param i        zero-based child index within this node's children array
     /// @param dtype    logical type to assign to the child context
     /// @param rowCount number of logical rows for the child
-    /// @return the decoded {@link Array} for child `i`
+    /// @return the decoded [Array] for child `i`
     public Array decodeChild(int i, DType dtype, long rowCount) {
         ArrayNode child = node.children()[i];
         var childCtx = new DecodeContext(child, dtype, rowCount, segmentBuffers, registry, arena);
@@ -60,7 +60,7 @@ public Array decodeChild(int i, DType dtype, long rowCount) {
     /// Recursively decode child `i` and return its primary backing segment.
     ///
     /// @param i zero-based child index within this node's children array
-    /// @return the primary {@link MemorySegment} of the decoded child
+    /// @return the primary [MemorySegment] of the decoded child
     public MemorySegment decodeChildSegment(int i) {
         ArrayNode child = node.children()[i];
         var childCtx = new DecodeContext(child, dtype, rowCount, segmentBuffers, registry, arena);
@@ -72,7 +72,7 @@ public MemorySegment decodeChildSegment(int i) {
     /// @param i        zero-based child index within this node's children array
     /// @param dtype    logical type to assign to the child context
     /// @param rowCount number of logical rows for the child
-    /// @return the primary {@link MemorySegment} of the decoded child
+    /// @return the primary [MemorySegment] of the decoded child
     public MemorySegment decodeChildSegment(int i, DType dtype, long rowCount) {
         ArrayNode child = node.children()[i];
         var childCtx = new DecodeContext(child, dtype, rowCount, segmentBuffers, registry, arena);
@@ -83,7 +83,7 @@ public MemorySegment decodeChildSegment(int i, DType dtype, long rowCount) {
     /// variants from this context's arena.
     ///
     /// Use when a decoder already holds a decoded child — e.g. after unwrapping a
-    /// {@link io.github.dfa1.vortex.reader.array.MaskedArray} for its validity — and needs the
+    /// [io.github.dfa1.vortex.reader.array.MaskedArray] for its validity — and needs the
     /// raw buffer for a bulk read, rather than re-decoding via [#decodeChildSegment(int)].
     ///
     /// @param arr the decoded array to materialise
@@ -95,14 +95,14 @@ public MemorySegment materialize(Array arr) {
     /// Returns the buffer at position `i` in this node's bufferIndices.
     ///
     /// @param i zero-based index into this node's `bufferIndices` array
-    /// @return the {@link MemorySegment} for the referenced segment buffer
+    /// @return the [MemorySegment] for the referenced segment buffer
     public MemorySegment buffer(int i) {
         return segmentBuffers[node.bufferIndices()[i]];
     }
 
     /// Returns the encoding-specific metadata bytes for this node, or `null` if absent.
     ///
-    /// @return the metadata {@link ByteBuffer}, or `null`
+    /// @return the metadata [ByteBuffer], or `null`
     public ByteBuffer metadata() {
         return node.metadata();
     }
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/DeltaEncodingDecoder.java b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/DeltaEncodingDecoder.java
index aff734d3..3c1d9d7f 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/DeltaEncodingDecoder.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/DeltaEncodingDecoder.java
@@ -21,7 +21,7 @@
 /// Read-only decoder for `fastlanes.delta`.
 public final class DeltaEncodingDecoder implements EncodingDecoder {
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public DeltaEncodingDecoder() {
     }
 
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/DictEncodingDecoder.java b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/DictEncodingDecoder.java
index 78710467..387678da 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/DictEncodingDecoder.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/DictEncodingDecoder.java
@@ -34,7 +34,7 @@
 /// make lazy wrapping non-trivial here — kept eager by design.
 public final class DictEncodingDecoder implements EncodingDecoder {
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public DictEncodingDecoder() {
     }
 
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/EncodingDecoder.java b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/EncodingDecoder.java
index c5af82b1..b5817cec 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/EncodingDecoder.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/EncodingDecoder.java
@@ -5,7 +5,7 @@
 import io.github.dfa1.vortex.encoding.EncodingId;
 
 /// Read-side decoding interface. Implementations live in the `reader` module and
-/// are discovered via {@link java.util.ServiceLoader}.
+/// are discovered via [java.util.ServiceLoader].
 ///
 /// Register via {@link io.github.dfa1.vortex.reader.ReadRegistry} — implementations
 /// are discoverable via {@link java.util.ServiceLoader}.
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/ExtEncodingDecoder.java b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/ExtEncodingDecoder.java
index ed78816f..174e532e 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/ExtEncodingDecoder.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/ExtEncodingDecoder.java
@@ -8,7 +8,7 @@
 /// Read-only decoder for `vortex.ext` — unwraps the storage-array child.
 public final class ExtEncodingDecoder implements EncodingDecoder {
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public ExtEncodingDecoder() {
     }
 
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/FixedSizeListEncodingDecoder.java b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/FixedSizeListEncodingDecoder.java
index 8476402c..5266613a 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/FixedSizeListEncodingDecoder.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/FixedSizeListEncodingDecoder.java
@@ -9,7 +9,7 @@
 /// Read-only decoder for `vortex.fixed_size_list`.
 public final class FixedSizeListEncodingDecoder implements EncodingDecoder {
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public FixedSizeListEncodingDecoder() {
     }
 
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/FrameOfReferenceEncodingDecoder.java b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/FrameOfReferenceEncodingDecoder.java
index 3276b660..73e592bd 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/FrameOfReferenceEncodingDecoder.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/FrameOfReferenceEncodingDecoder.java
@@ -19,7 +19,7 @@
 /// Read-only decoder for `fastlanes.for` (Frame of Reference).
 public final class FrameOfReferenceEncodingDecoder implements EncodingDecoder {
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public FrameOfReferenceEncodingDecoder() {
     }
 
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/FsstEncodingDecoder.java b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/FsstEncodingDecoder.java
index 8f1fe792..e4ad348e 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/FsstEncodingDecoder.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/FsstEncodingDecoder.java
@@ -19,7 +19,7 @@ public final class FsstEncodingDecoder implements EncodingDecoder {
 
     private static final int ESCAPE = 0xFF;
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public FsstEncodingDecoder() {
     }
 
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/KnownArrayNode.java b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/KnownArrayNode.java
index a82420d8..172ae253 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/KnownArrayNode.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/KnownArrayNode.java
@@ -4,7 +4,7 @@
 
 import java.nio.ByteBuffer;
 
-/// Array node whose encoding id is well-known to this build (an {@link EncodingId} enum constant).
+/// Array node whose encoding id is well-known to this build (an [EncodingId] enum constant).
 ///
 /// @param encodingId    well-known encoding id
 /// @param metadata      encoding-specific metadata bytes, or `null`
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/LeBitReader.java b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/LeBitReader.java
index a8ec2fd9..f5431056 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/LeBitReader.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/LeBitReader.java
@@ -5,7 +5,7 @@
 import java.lang.foreign.MemorySegment;
 import java.lang.foreign.ValueLayout;
 
-/// Little-endian bit reader over a {@link MemorySegment}.
+/// Little-endian bit reader over a [MemorySegment].
 ///
 /// Bits are packed LSB-first within each byte (pcodec wire format convention).
 /// Bit 0 of the stream is the LSB of byte 0; bit 8 is the LSB of byte 1.
@@ -62,7 +62,7 @@ public void alignToByte() {
         }
     }
 
-    /// Current byte offset (only meaningful after {@link #alignToByte()}).
+    /// Current byte offset (only meaningful after [#alignToByte()]).
     ///
     /// @return current stream position in bytes
     public long byteOffset() {
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/ListEncodingDecoder.java b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/ListEncodingDecoder.java
index ddc7567b..46eddc32 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/ListEncodingDecoder.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/ListEncodingDecoder.java
@@ -14,7 +14,7 @@
 /// Read-only decoder for `vortex.list`.
 public final class ListEncodingDecoder implements EncodingDecoder {
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public ListEncodingDecoder() {
     }
 
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/ListViewEncodingDecoder.java b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/ListViewEncodingDecoder.java
index 0d75181b..a94e1f10 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/ListViewEncodingDecoder.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/ListViewEncodingDecoder.java
@@ -14,7 +14,7 @@
 /// Read-only decoder for `vortex.listview`.
 public final class ListViewEncodingDecoder implements EncodingDecoder {
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public ListViewEncodingDecoder() {
     }
 
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/MaskedEncodingDecoder.java b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/MaskedEncodingDecoder.java
index 1487a06e..4f75fd4a 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/MaskedEncodingDecoder.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/MaskedEncodingDecoder.java
@@ -10,7 +10,7 @@
 /// Read-only decoder for `vortex.masked` — payload child + optional validity bitmap child.
 public final class MaskedEncodingDecoder implements EncodingDecoder {
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public MaskedEncodingDecoder() {
     }
 
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/NullEncodingDecoder.java b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/NullEncodingDecoder.java
index 33593561..ebc034ff 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/NullEncodingDecoder.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/NullEncodingDecoder.java
@@ -8,7 +8,7 @@
 /// Read-only decoder for `vortex.null` (all-null arrays).
 public final class NullEncodingDecoder implements EncodingDecoder {
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public NullEncodingDecoder() {
     }
 
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/PatchedEncodingDecoder.java b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/PatchedEncodingDecoder.java
index ac9dc8ad..3c26a95e 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/PatchedEncodingDecoder.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/PatchedEncodingDecoder.java
@@ -21,7 +21,7 @@
 /// Read-only decoder for `vortex.patched`.
 public final class PatchedEncodingDecoder implements EncodingDecoder {
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public PatchedEncodingDecoder() {
     }
 
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/PcoEncodingDecoder.java b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/PcoEncodingDecoder.java
index f44b9918..6a08d8a0 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/PcoEncodingDecoder.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/PcoEncodingDecoder.java
@@ -34,7 +34,7 @@ public final class PcoEncodingDecoder implements EncodingDecoder {
     private static final ValueLayout.OfLong LE_LONG =
             ValueLayout.JAVA_LONG_UNALIGNED.withOrder(ByteOrder.LITTLE_ENDIAN);
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public PcoEncodingDecoder() {
     }
 
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/PcoTansDecoder.java b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/PcoTansDecoder.java
index 12404967..877fb0e8 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/PcoTansDecoder.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/PcoTansDecoder.java
@@ -9,7 +9,7 @@
 
 /// 4-way interleaved tANS decoder for one pco latent variable.
 ///
-/// Build via {@link #build(int, PcoBin[])}; then call {@link #decodePage} once per page.
+/// Build via [#build(int, PcoBin[])]; then call [#decodePage] once per page.
 /// Port of `pco/src/ans/spec.rs` (spread) and `pco/src/ans/decoding.rs` (nodes).
 public final class PcoTansDecoder {
 
@@ -92,7 +92,7 @@ static int[] spreadStateSymbols(int[] weights, int tableSize) {
     /// Decode `n` raw latent values (U64) from `reader` into `out`.
     ///
     /// Caller must have already read 4 initial ANS state indices and called
-    /// {@link LeBitReader#alignToByte()} before this call.
+    /// [LeBitReader#alignToByte()] before this call.
     /// `ansStateIdxs` is modified in place and not valid after return.
     /// `batchLowers` and `batchOffsetBits` are caller-provided scratch arrays of
     /// length ≥ {@link #BATCH_N}; they are fully overwritten before use.
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/PrimitiveEncodingDecoder.java b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/PrimitiveEncodingDecoder.java
index 80bde249..9f405f3a 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/PrimitiveEncodingDecoder.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/PrimitiveEncodingDecoder.java
@@ -20,7 +20,7 @@
 /// Read-only decoder for `vortex.primitive` — raw little-endian primitive arrays.
 public final class PrimitiveEncodingDecoder implements EncodingDecoder {
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public PrimitiveEncodingDecoder() {
     }
 
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/RleEncodingDecoder.java b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/RleEncodingDecoder.java
index 30824704..98caa8bc 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/RleEncodingDecoder.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/RleEncodingDecoder.java
@@ -29,7 +29,7 @@ public final class RleEncodingDecoder implements EncodingDecoder {
 
     private static final int FL_CHUNK_SIZE = 1024;
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public RleEncodingDecoder() {
     }
 
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/RunEndEncodingDecoder.java b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/RunEndEncodingDecoder.java
index 47fd1f48..689d4236 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/RunEndEncodingDecoder.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/RunEndEncodingDecoder.java
@@ -29,7 +29,7 @@
 /// Read-only decoder for `vortex.runend`.
 public final class RunEndEncodingDecoder implements EncodingDecoder {
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public RunEndEncodingDecoder() {
     }
 
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/SegmentBroadcast.java b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/SegmentBroadcast.java
index f2ec4e82..4105ec9e 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/SegmentBroadcast.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/SegmentBroadcast.java
@@ -12,7 +12,7 @@
 /// `MemorySegment.copy(seg, i * elemBytes, ...)`) must replicate the lone element across
 /// every logical index instead of running off the end.
 ///
-/// {@link io.github.dfa1.vortex.reader.array.LongArray#getLong(long)} and the sibling typed
+/// [io.github.dfa1.vortex.reader.array.LongArray#getLong(long)] and the sibling typed
 /// accessors already wrap around with `i % cap`; this helper exposes the same arithmetic
 /// to call sites that work with raw segments.
 public final class SegmentBroadcast {
@@ -26,7 +26,7 @@ private SegmentBroadcast() {
     /// @param seg       segment returned by DecodeContext#decodeChildSegment
     /// @param i         logical element index in `[0, rowCount)`
     /// @param elemBytes element width in bytes (>= 1)
-    /// @return byte offset suitable for {@link MemorySegment#get} or
+    /// @return byte offset suitable for [MemorySegment#get] or
     ///         {@link MemorySegment#copy(MemorySegment, long, MemorySegment, long, long)}
     /// @throws VortexException if `seg` is empty (zero elements)
     public static long elementOffset(MemorySegment seg, long i, int elemBytes) {
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/SequenceEncodingDecoder.java b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/SequenceEncodingDecoder.java
index d9220a5b..2a3e30fe 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/SequenceEncodingDecoder.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/SequenceEncodingDecoder.java
@@ -25,7 +25,7 @@
 /// Read-only decoder for `vortex.sequence` — `A[i] = base + i * multiplier`.
 public final class SequenceEncodingDecoder implements EncodingDecoder {
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public SequenceEncodingDecoder() {
     }
 
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/SparseEncodingDecoder.java b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/SparseEncodingDecoder.java
index 484a3316..cc7df618 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/SparseEncodingDecoder.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/SparseEncodingDecoder.java
@@ -34,7 +34,7 @@
 /// Read-only decoder for `vortex.sparse`.
 public final class SparseEncodingDecoder implements EncodingDecoder {
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public SparseEncodingDecoder() {
     }
 
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/StructEncodingDecoder.java b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/StructEncodingDecoder.java
index e78fa44b..7c47990b 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/StructEncodingDecoder.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/StructEncodingDecoder.java
@@ -14,7 +14,7 @@
 /// Read-only decoder for `vortex.struct`.
 public final class StructEncodingDecoder implements EncodingDecoder {
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public StructEncodingDecoder() {
     }
 
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/UnknownArrayNode.java b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/UnknownArrayNode.java
index f51e4361..04cf80c1 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/UnknownArrayNode.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/UnknownArrayNode.java
@@ -2,7 +2,7 @@
 
 import java.nio.ByteBuffer;
 
-/// Array node whose encoding id is not a recognised {@link io.github.dfa1.vortex.encoding.EncodingId}.
+/// Array node whose encoding id is not a recognised [io.github.dfa1.vortex.encoding.EncodingId].
 /// Produced when a file uses an encoding this build does not know about. Decoded as
 /// {@link io.github.dfa1.vortex.reader.array.UnknownArray} when
 /// {@link io.github.dfa1.vortex.reader.ReadRegistry#isAllowUnknown()} is set; otherwise the decode call throws.
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/VarBinEncodingDecoder.java b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/VarBinEncodingDecoder.java
index f23607d5..e43642d7 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/VarBinEncodingDecoder.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/VarBinEncodingDecoder.java
@@ -15,7 +15,7 @@
 /// Read-only decoder for `vortex.varbin`.
 public final class VarBinEncodingDecoder implements EncodingDecoder {
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public VarBinEncodingDecoder() {
     }
 
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/VarBinViewEncodingDecoder.java b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/VarBinViewEncodingDecoder.java
index 8d02687b..0b84f43d 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/VarBinViewEncodingDecoder.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/VarBinViewEncodingDecoder.java
@@ -11,7 +11,7 @@
 /// Read-only decoder for `vortex.varbinview` (Apache Arrow StringView/BinaryView).
 public final class VarBinViewEncodingDecoder implements EncodingDecoder {
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public VarBinViewEncodingDecoder() {
     }
 
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/VariantEncodingDecoder.java b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/VariantEncodingDecoder.java
index 54b6f27e..029c5f80 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/VariantEncodingDecoder.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/VariantEncodingDecoder.java
@@ -17,7 +17,7 @@
 /// Read-only decoder for `vortex.variant`.
 public final class VariantEncodingDecoder implements EncodingDecoder {
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public VariantEncodingDecoder() {
     }
 
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/ZigZagEncodingDecoder.java b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/ZigZagEncodingDecoder.java
index 80177c49..9a295aa1 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/ZigZagEncodingDecoder.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/ZigZagEncodingDecoder.java
@@ -21,7 +21,7 @@
 /// Read-only decoder for `vortex.zigzag` — zigzag-decoded signed integers.
 public final class ZigZagEncodingDecoder implements EncodingDecoder {
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public ZigZagEncodingDecoder() {
     }
 
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/ZstdEncodingDecoder.java b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/ZstdEncodingDecoder.java
index 0cde71fe..c57094f1 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/decode/ZstdEncodingDecoder.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/decode/ZstdEncodingDecoder.java
@@ -29,7 +29,7 @@
 /// Read-only decoder for `vortex.zstd`.
 public final class ZstdEncodingDecoder implements EncodingDecoder {
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public ZstdEncodingDecoder() {
     }
 
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/extension/DateExtensionDecoder.java b/reader/src/main/java/io/github/dfa1/vortex/reader/extension/DateExtensionDecoder.java
index aa3e1de1..d0a8a1fe 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/extension/DateExtensionDecoder.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/extension/DateExtensionDecoder.java
@@ -21,7 +21,7 @@ public final class DateExtensionDecoder implements ExtensionDecoder {
     /// Singleton instance.
     public static final DateExtensionDecoder INSTANCE = new DateExtensionDecoder();
 
-    /// Public no-arg constructor for {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor for [java.util.ServiceLoader].
     /// Prefer the {@link #INSTANCE} singleton in application code.
     public DateExtensionDecoder() {
     }
@@ -54,7 +54,7 @@ public LocalDate decode(Array storage, long i) {
         return LocalDate.ofEpochDay(ExtensionStorage.epochInteger(storage, i));
     }
 
-    /// Decodes every row of `storage` into a list of dates. {@link MaskedArray}
+    /// Decodes every row of `storage` into a list of dates. [MaskedArray]
     /// storage yields `null` at invalid positions instead of throwing.
     ///
     /// @param storage signed-integer storage array (optionally wrapped in `MaskedArray`)
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/extension/ExtensionStorage.java b/reader/src/main/java/io/github/dfa1/vortex/reader/extension/ExtensionStorage.java
index 5fbf18ae..89e44946 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/extension/ExtensionStorage.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/extension/ExtensionStorage.java
@@ -20,7 +20,7 @@ private ExtensionStorage() {
     }
 
     /// Reads a signed integer from any of the integer primitive arrays as `long`.
-    /// Recurses through {@link MaskedArray}; throws on null cells so callers don't silently
+    /// Recurses through [MaskedArray]; throws on null cells so callers don't silently
     /// get garbage for nullable columns.
     ///
     /// @param storage signed-integer storage array
@@ -44,7 +44,7 @@ public static long epochInteger(Array storage, long i) {
         };
     }
 
-    /// Reads the {@link TimeUnit} metadata byte at the buffer's current position;
+    /// Reads the [TimeUnit] metadata byte at the buffer's current position;
     /// throws if the buffer is null or empty.
     ///
     /// @param ext declared extension dtype
@@ -58,7 +58,7 @@ public static TimeUnit readUnit(DType.Extension ext) {
         return TimeUnit.fromTag(meta.get(meta.position()));
     }
 
-    /// Constructs an {@link Instant} from a signed epoch count in the given unit.
+    /// Constructs an [Instant] from a signed epoch count in the given unit.
     ///
     /// @param raw  epoch count
     /// @param unit time resolution; must not be {@link TimeUnit#Days}
@@ -82,7 +82,7 @@ public static Instant instantFromRaw(long raw, TimeUnit unit) {
         };
     }
 
-    /// Throws {@link IndexOutOfBoundsException} if `i` is outside `[0, length)`.
+    /// Throws [IndexOutOfBoundsException] if `i` is outside `[0, length)`.
     ///
     /// @param i      row index to check
     /// @param length array length
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/extension/TimeExtensionDecoder.java b/reader/src/main/java/io/github/dfa1/vortex/reader/extension/TimeExtensionDecoder.java
index 25645139..861930b2 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/extension/TimeExtensionDecoder.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/extension/TimeExtensionDecoder.java
@@ -14,13 +14,13 @@
 import java.util.ArrayList;
 import java.util.List;
 
-/// `vortex.time` — sub-day count in the {@link TimeUnit} recorded in the metadata byte.
+/// `vortex.time` — sub-day count in the [TimeUnit] recorded in the metadata byte.
 public final class TimeExtensionDecoder implements ExtensionDecoder {
 
     /// Singleton instance.
     public static final TimeExtensionDecoder INSTANCE = new TimeExtensionDecoder();
 
-    /// Public no-arg constructor for {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor for [java.util.ServiceLoader].
     /// Prefer the {@link #INSTANCE} singleton in application code.
     public TimeExtensionDecoder() {
     }
@@ -48,7 +48,7 @@ public DType.Extension dtype(TimeUnit unit, boolean nullable) {
 
     /// Decodes the time-of-day cell at row `i`.
     ///
-    /// @param ext     declared extension dtype carrying the {@link TimeUnit} byte
+    /// @param ext     declared extension dtype carrying the [TimeUnit] byte
     /// @param storage signed-integer storage (I32 for s/ms, I64 for μs/ns)
     /// @param i       row index, `0 <= i < storage.length()`
     /// @return decoded local time
@@ -65,7 +65,7 @@ public LocalTime decode(DType.Extension ext, Array storage, long i) {
         return LocalTime.ofNanoOfDay(nanos);
     }
 
-    /// Decodes every row of `storage` into a list of times. {@link MaskedArray}
+    /// Decodes every row of `storage` into a list of times. [MaskedArray]
     /// storage yields `null` at invalid positions instead of throwing.
     ///
     /// @param ext     declared extension dtype carrying the unit
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/extension/TimestampExtensionDecoder.java b/reader/src/main/java/io/github/dfa1/vortex/reader/extension/TimestampExtensionDecoder.java
index 1380a70f..023ba91f 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/extension/TimestampExtensionDecoder.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/extension/TimestampExtensionDecoder.java
@@ -51,7 +51,7 @@ public DType.Extension dtype(TimeUnit unit, ZoneId zone, boolean nullable) {
         return TimestampDtype.of(unit, zone, nullable);
     }
 
-    /// Decodes the timestamp cell at row `i` to an {@link Instant}, ignoring timezone.
+    /// Decodes the timestamp cell at row `i` to an [Instant], ignoring timezone.
     ///
     /// @param ext     declared extension dtype
     /// @param storage signed-integer storage array
@@ -68,7 +68,7 @@ public Instant instant(DType.Extension ext, Array storage, long i) {
         return ExtensionStorage.instantFromRaw(ExtensionStorage.epochInteger(storage, i), unit);
     }
 
-    /// Decodes the timestamp cell at row `i` to a {@link ZonedDateTime}
+    /// Decodes the timestamp cell at row `i` to a [ZonedDateTime]
     /// using the timezone from the metadata, defaulting to UTC when absent.
     ///
     /// @param ext     declared extension dtype
@@ -88,7 +88,7 @@ public Optional<ZoneId> timezone(DType.Extension ext) {
         return TimestampDtype.timezone(ext);
     }
 
-    /// Decodes every row of `storage` into a list of instants. {@link MaskedArray}
+    /// Decodes every row of `storage` into a list of instants. [MaskedArray]
     /// storage yields `null` at invalid positions instead of throwing.
     ///
     /// @param ext     declared extension dtype carrying the unit
diff --git a/reader/src/main/java/io/github/dfa1/vortex/reader/extension/UuidExtensionDecoder.java b/reader/src/main/java/io/github/dfa1/vortex/reader/extension/UuidExtensionDecoder.java
index 2cb102ad..d3f3cf72 100644
--- a/reader/src/main/java/io/github/dfa1/vortex/reader/extension/UuidExtensionDecoder.java
+++ b/reader/src/main/java/io/github/dfa1/vortex/reader/extension/UuidExtensionDecoder.java
@@ -22,7 +22,7 @@ public final class UuidExtensionDecoder implements ExtensionDecoder {
     /// Singleton instance.
     public static final UuidExtensionDecoder INSTANCE = new UuidExtensionDecoder();
 
-    /// Public no-arg constructor for {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor for [java.util.ServiceLoader].
     /// Prefer the {@link #INSTANCE} singleton in application code.
     public UuidExtensionDecoder() {
     }
@@ -48,7 +48,7 @@ public DType.Extension dtype(boolean nullable) {
     ///
     /// @param storage UUID storage array
     /// @param i       row index, `0 <= i < storage.length()`
-    /// @return decoded {@link UUID}
+    /// @return decoded [UUID]
     /// @throws VortexException if storage isn't a `FixedSizeListArray<ByteArray>` of size 16
     public UUID decode(Array storage, long i) {
         ExtensionStorage.checkBounds(i, storage.length());
@@ -81,7 +81,7 @@ public UUID decode(Array storage, long i) {
         return new UUID(msb, lsb);
     }
 
-    /// Decodes every row of `storage` into a list of UUIDs. {@link MaskedArray}
+    /// Decodes every row of `storage` into a list of UUIDs. [MaskedArray]
     /// storage yields `null` at invalid positions instead of throwing.
     ///
     /// @param storage UUID storage array (optionally wrapped in `MaskedArray`)
diff --git a/reader/src/test/java/io/github/dfa1/vortex/reader/array/ArrayLimitedTest.java b/reader/src/test/java/io/github/dfa1/vortex/reader/array/ArrayLimitedTest.java
index 927afac6..943799ec 100644
--- a/reader/src/test/java/io/github/dfa1/vortex/reader/array/ArrayLimitedTest.java
+++ b/reader/src/test/java/io/github/dfa1/vortex/reader/array/ArrayLimitedTest.java
@@ -213,7 +213,7 @@ void limitAcrossBoundaryKeepsPrefixAndCutsBoundaryChild() {
 
             // Then — first chunk kept whole, boundary chunk truncated to 1 row
             assertThat(result.length()).isEqualTo(4L);
-            assertThat(((LongArray) result).getLong(0)).isEqualTo(0L);
+            assertThat(((LongArray) result).getLong(0)).isZero();
             assertThat(((LongArray) result).getLong(3)).isEqualTo(3L);
         }
 
diff --git a/reader/src/test/java/io/github/dfa1/vortex/reader/array/LazyDateTimePartsLongArrayTest.java b/reader/src/test/java/io/github/dfa1/vortex/reader/array/LazyDateTimePartsLongArrayTest.java
index 149bed4e..fe50f73b 100644
--- a/reader/src/test/java/io/github/dfa1/vortex/reader/array/LazyDateTimePartsLongArrayTest.java
+++ b/reader/src/test/java/io/github/dfa1/vortex/reader/array/LazyDateTimePartsLongArrayTest.java
@@ -7,7 +7,7 @@
 import static io.github.dfa1.vortex.reader.array.TestArrays.longs;
 import static org.assertj.core.api.Assertions.assertThat;
 
-/// Unit tests for {@link LazyDateTimePartsLongArray}. Verifies the
+/// Unit tests for [LazyDateTimePartsLongArray]. Verifies the
 /// `days * unitsPerDay + seconds * unitsPerSecond + subseconds`
 /// reassembly across the supported time units, and the widening read path
 /// that lets each child use whatever signed-integer ptype the encoder picked.
diff --git a/reader/src/test/java/io/github/dfa1/vortex/reader/array/LazyZigZagIntArrayTest.java b/reader/src/test/java/io/github/dfa1/vortex/reader/array/LazyZigZagIntArrayTest.java
index 64acfd67..3d57d8e6 100644
--- a/reader/src/test/java/io/github/dfa1/vortex/reader/array/LazyZigZagIntArrayTest.java
+++ b/reader/src/test/java/io/github/dfa1/vortex/reader/array/LazyZigZagIntArrayTest.java
@@ -34,7 +34,7 @@ void getIntAppliesZigzagDecode() {
         LazyZigZagIntArray sut = of(0, 1, 2, 3, 4);
 
         // When + Then
-        assertThat(sut.getInt(0)).isEqualTo(0);
+        assertThat(sut.getInt(0)).isZero();
         assertThat(sut.getInt(1)).isEqualTo(-1);
         assertThat(sut.getInt(2)).isEqualTo(1);
         assertThat(sut.getInt(3)).isEqualTo(-2);
@@ -63,6 +63,6 @@ void foldSumApplies() {
         int sum = sut.fold(0, Integer::sum);
 
         // Then
-        assertThat(sum).isEqualTo(0);
+        assertThat(sum).isZero();
     }
 }
diff --git a/reader/src/test/java/io/github/dfa1/vortex/reader/array/LazyZigZagLongArrayTest.java b/reader/src/test/java/io/github/dfa1/vortex/reader/array/LazyZigZagLongArrayTest.java
index c3ff19cc..fda644c1 100644
--- a/reader/src/test/java/io/github/dfa1/vortex/reader/array/LazyZigZagLongArrayTest.java
+++ b/reader/src/test/java/io/github/dfa1/vortex/reader/array/LazyZigZagLongArrayTest.java
@@ -34,7 +34,7 @@ void getLongAppliesZigzagDecode() {
         LazyZigZagLongArray sut = of(0L, 1L, 2L, 3L, 4L);
 
         // When + Then
-        assertThat(sut.getLong(0)).isEqualTo(0L);
+        assertThat(sut.getLong(0)).isZero();
         assertThat(sut.getLong(1)).isEqualTo(-1L);
         assertThat(sut.getLong(2)).isEqualTo(1L);
         assertThat(sut.getLong(3)).isEqualTo(-2L);
@@ -63,6 +63,6 @@ void foldSumApplies() {
         long sum = sut.fold(0L, Long::sum);
 
         // Then
-        assertThat(sum).isEqualTo(0L);
+        assertThat(sum).isZero();
     }
 }
diff --git a/reader/src/test/java/io/github/dfa1/vortex/reader/array/VarBinViewModeTest.java b/reader/src/test/java/io/github/dfa1/vortex/reader/array/VarBinViewModeTest.java
index 60653e8a..e507c148 100644
--- a/reader/src/test/java/io/github/dfa1/vortex/reader/array/VarBinViewModeTest.java
+++ b/reader/src/test/java/io/github/dfa1/vortex/reader/array/VarBinViewModeTest.java
@@ -13,7 +13,7 @@
 
 import static org.assertj.core.api.Assertions.assertThat;
 
-/// Unit tests for {@link VarBinArray.ViewMode}. Covers inline (≤ 12 byte) views,
+/// Unit tests for [VarBinArray.ViewMode]. Covers inline (≤ 12 byte) views,
 /// referenced views into shared data buffers, length-only reads, and truncate.
 class VarBinViewModeTest {
 
diff --git a/reader/src/test/java/io/github/dfa1/vortex/reader/decode/LeBitReaderTest.java b/reader/src/test/java/io/github/dfa1/vortex/reader/decode/LeBitReaderTest.java
index acdc1eab..4f2aa03b 100644
--- a/reader/src/test/java/io/github/dfa1/vortex/reader/decode/LeBitReaderTest.java
+++ b/reader/src/test/java/io/github/dfa1/vortex/reader/decode/LeBitReaderTest.java
@@ -146,7 +146,7 @@ void sequential_reads_advance_position() {
             // Then — 0xAB = 0b10101011, LSB first: 1,1,0,1,0,1,0,1
             assertThat(b0).isEqualTo(1);
             assertThat(b1).isEqualTo(1);
-            assertThat(b2).isEqualTo(0);
+            assertThat(b2).isZero();
             assertThat(b3).isEqualTo(1);
             assertThat(sut.bitsConsumed()).isEqualTo(4);
         }
diff --git a/reader/src/test/java/io/github/dfa1/vortex/reader/decode/PatchedEncodingDecoderTest.java b/reader/src/test/java/io/github/dfa1/vortex/reader/decode/PatchedEncodingDecoderTest.java
index 27856da2..ecf3c120 100644
--- a/reader/src/test/java/io/github/dfa1/vortex/reader/decode/PatchedEncodingDecoderTest.java
+++ b/reader/src/test/java/io/github/dfa1/vortex/reader/decode/PatchedEncodingDecoderTest.java
@@ -127,8 +127,8 @@ void decode_multiplePatches_allApplied() {
         // Then
         IntArray ints = (IntArray) result;
         assertThat(ints.getInt(0)).isEqualTo(1);
-        assertThat(ints.getInt(1)).isEqualTo(0);
-        assertThat(ints.getInt(2)).isEqualTo(0);
+        assertThat(ints.getInt(1)).isZero();
+        assertThat(ints.getInt(2)).isZero();
         assertThat(ints.getInt(3)).isEqualTo(7);
     }
 
diff --git a/reader/src/test/java/io/github/dfa1/vortex/reader/decode/PcoEncodingDecoderTest.java b/reader/src/test/java/io/github/dfa1/vortex/reader/decode/PcoEncodingDecoderTest.java
index 98b3ec7b..dbb939df 100644
--- a/reader/src/test/java/io/github/dfa1/vortex/reader/decode/PcoEncodingDecoderTest.java
+++ b/reader/src/test/java/io/github/dfa1/vortex/reader/decode/PcoEncodingDecoderTest.java
@@ -452,7 +452,7 @@ void randomChunkMetaBytes_neverThrowsJvmException(byte[] chunkMetaBytes) {
             assertThatCode(() -> {
                 try {
                     SUT.decode(ctx);
-                } catch (VortexException ignored) {
+                } catch (VortexException _) {
                 }
             }).doesNotThrowAnyException();
         }
@@ -467,7 +467,7 @@ void randomPageBytes_classicMode_neverThrowsJvmException(byte[] pageBytes) {
             assertThatCode(() -> {
                 try {
                     SUT.decode(ctx);
-                } catch (VortexException ignored) {
+                } catch (VortexException _) {
                 }
             }).doesNotThrowAnyException();
         }
diff --git a/reader/src/test/java/io/github/dfa1/vortex/reader/decode/SegmentBroadcastTest.java b/reader/src/test/java/io/github/dfa1/vortex/reader/decode/SegmentBroadcastTest.java
index b410f6b5..21bc25b0 100644
--- a/reader/src/test/java/io/github/dfa1/vortex/reader/decode/SegmentBroadcastTest.java
+++ b/reader/src/test/java/io/github/dfa1/vortex/reader/decode/SegmentBroadcastTest.java
@@ -8,7 +8,7 @@
 
 import static org.assertj.core.api.Assertions.assertThat;
 
-/// Unit tests for {@link SegmentBroadcast}. These verify the wrap-on-broadcast
+/// Unit tests for [SegmentBroadcast]. These verify the wrap-on-broadcast
 /// semantics that protect downstream encoders/decoders from IOOB when a child
 /// segment was produced by {@link ConstantEncoding} (single-element buffer).
 class SegmentBroadcastTest {
diff --git a/reader/src/test/java/io/github/dfa1/vortex/reader/decode/TestDecodeContexts.java b/reader/src/test/java/io/github/dfa1/vortex/reader/decode/TestDecodeContexts.java
index eb656ccd..e6b2c8df 100644
--- a/reader/src/test/java/io/github/dfa1/vortex/reader/decode/TestDecodeContexts.java
+++ b/reader/src/test/java/io/github/dfa1/vortex/reader/decode/TestDecodeContexts.java
@@ -6,7 +6,7 @@
 import java.lang.foreign.Arena;
 import java.lang.foreign.MemorySegment;
 
-/// Fluent builder for {@link DecodeContext} used in encoding tests.
+/// Fluent builder for [DecodeContext] used in encoding tests.
 ///
 /// Defaults: rowCount=0, segments=[], registry=empty, arena=Arena.global().
 ///
@@ -70,7 +70,7 @@ public TestDecodeContexts arena(Arena a) {
         return this;
     }
 
-    /// Builds the {@link DecodeContext}.
+    /// Builds the [DecodeContext].
     ///
     /// @return a new decode context
     public DecodeContext build() {
diff --git a/reader/src/test/java/io/github/dfa1/vortex/reader/decode/TestRegistry.java b/reader/src/test/java/io/github/dfa1/vortex/reader/decode/TestRegistry.java
index 23561c2a..978814f6 100644
--- a/reader/src/test/java/io/github/dfa1/vortex/reader/decode/TestRegistry.java
+++ b/reader/src/test/java/io/github/dfa1/vortex/reader/decode/TestRegistry.java
@@ -2,7 +2,7 @@
 
 import io.github.dfa1.vortex.reader.ReadRegistry;
 
-/// Static factories for {@link ReadRegistry} instances used in decode tests.
+/// Static factories for [ReadRegistry] instances used in decode tests.
 ///
 /// Public so writer/ test trees can reuse via the reader test-jar.
 public final class TestRegistry {
@@ -10,7 +10,7 @@ public final class TestRegistry {
     private TestRegistry() {
     }
 
-    /// Builds a {@link ReadRegistry} containing only the supplied decoders.
+    /// Builds a [ReadRegistry] containing only the supplied decoders.
     ///
     /// @param decoders decoders to register
     /// @return registry instance
@@ -22,7 +22,7 @@ public static ReadRegistry ofDecoders(EncodingDecoder... decoders) {
         return b.build();
     }
 
-    /// Builds a {@link ReadRegistry} containing the supplied decoder plus a
+    /// Builds a [ReadRegistry] containing the supplied decoder plus a
     /// {@link PrimitiveEncodingDecoder} fallback (so child decodes of primitive segments work).
     ///
     /// @param sut decoder under test
diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/Chunk.java b/writer/src/main/java/io/github/dfa1/vortex/writer/Chunk.java
index cf70e042..439f5d72 100644
--- a/writer/src/main/java/io/github/dfa1/vortex/writer/Chunk.java
+++ b/writer/src/main/java/io/github/dfa1/vortex/writer/Chunk.java
@@ -1,6 +1,6 @@
 package io.github.dfa1.vortex.writer;
 
-/// Typed chunk builder for {@link VortexWriter#writeChunk(java.util.function.Consumer)}.
+/// Typed chunk builder for [VortexWriter#writeChunk(java.util.function.Consumer)].
 ///
 /// Validates each `put` against the writer's schema:
 /// - Column name must exist in the schema.
diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/ExtensionEncoder.java b/writer/src/main/java/io/github/dfa1/vortex/writer/ExtensionEncoder.java
index f21ef04e..16e0573c 100644
--- a/writer/src/main/java/io/github/dfa1/vortex/writer/ExtensionEncoder.java
+++ b/writer/src/main/java/io/github/dfa1/vortex/writer/ExtensionEncoder.java
@@ -8,7 +8,7 @@
 
 /// Write-side contract for a Vortex extension type.
 ///
-/// Implementations pair a spec identity ({@link ExtensionId}) with the matching
+/// Implementations pair a spec identity ([ExtensionId]) with the matching
 /// {@link DType.Extension} dtype and a polymorphic {@link #encodeAll} entry point used
 /// by the writer's auto-routing path.
 public interface ExtensionEncoder {
@@ -17,7 +17,7 @@ public interface ExtensionEncoder {
     ExtensionId extensionId();
 
     /// @param nullable whether the column allows nulls
-    /// @return matching {@link DType.Extension} (storage dtype + default metadata)
+    /// @return matching [DType.Extension] (storage dtype + default metadata)
     DType.Extension dtype(boolean nullable);
 
     /// Polymorphic encode: converts a collection of domain values into the raw
diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/VortexWriter.java b/writer/src/main/java/io/github/dfa1/vortex/writer/VortexWriter.java
index f7e02fd0..85d949b0 100644
--- a/writer/src/main/java/io/github/dfa1/vortex/writer/VortexWriter.java
+++ b/writer/src/main/java/io/github/dfa1/vortex/writer/VortexWriter.java
@@ -122,7 +122,7 @@ private VortexWriter(
         }
     }
 
-    /// Builds a {@link WriteRegistry} from the given encoder list plus all service-loaded extensions.
+    /// Builds a [WriteRegistry] from the given encoder list plus all service-loaded extensions.
     private static WriteRegistry buildRegistry(List<EncodingEncoder> encoders) {
         WriteRegistry.Builder b = WriteRegistry.builder();
         for (EncodingEncoder e : encoders) {
@@ -171,7 +171,7 @@ private static List<EncodingEncoder> buildCascadeCodecs(WriteOptions options) {
         return List.copyOf(codecs);
     }
 
-    /// Creates a {@link VortexWriter} using the default encoder set.
+    /// Creates a [VortexWriter] using the default encoder set.
     ///
     /// @param channel the channel to write to
     /// @param schema  the struct schema for the file
@@ -183,7 +183,7 @@ public static VortexWriter create(
         return new VortexWriter(channel, schema, options, DEFAULT_CODECS);
     }
 
-    /// Creates a {@link VortexWriter} with a custom encoder list.
+    /// Creates a [VortexWriter] with a custom encoder list.
     ///
     /// Creates a {@link VortexWriter} with a custom encoder list.
     ///
@@ -200,7 +200,7 @@ public static VortexWriter create(
         return new VortexWriter(channel, schema, options.withGlobalDict(false), encodings);
     }
 
-    /// Creates a {@link VortexWriter} with a custom {@link WriteRegistry}.
+    /// Creates a [VortexWriter] with a custom [WriteRegistry].
     ///
     /// @param channel  the channel to write to
     /// @param schema   the struct schema for the file
@@ -214,7 +214,7 @@ public static VortexWriter create(
                 List.copyOf(registry.encoderMap().values()));
     }
 
-    /// Counts rows for the length-consistency check in {@link #writeChunk}. Accepts the
+    /// Counts rows for the length-consistency check in [#writeChunk]. Accepts the
     /// same shapes the writer takes plus pre-conversion {@link java.util.Collection}s
     /// from the extension-column auto-route path.
     private static long rowCountForValidation(String colName, Object data) {
@@ -223,7 +223,7 @@ private static long rowCountForValidation(String colName, Object data) {
         }
         try {
             return arrayLength(data);
-        } catch (UnsupportedOperationException e) {
+        } catch (UnsupportedOperationException _) {
             throw new IllegalArgumentException(
                     "column '" + colName + "' has unsupported data type: "
                             + data.getClass().getSimpleName());
@@ -346,7 +346,7 @@ private static ByteBuffer buildPostscript(
 
     // ── Segment encoding ─────────────────────────────────────────────────────
 
-    /// Write one chunk via the typed {@link Chunk} builder. Each `.put` is validated
+    /// Write one chunk via the typed [Chunk] builder. Each `.put` is validated
     /// against the writer's schema (name exists, array type matches dtype, boxed arrays for
     /// nullable columns); after the consumer returns, every schema column must have been
     /// supplied and all column arrays must share the same length.
@@ -480,7 +480,7 @@ private int writeSegment(DType dtype, Object data) throws IOException {
     /// Writes a segment, optionally forcing a specific `encodingOverride` instead of
     /// the configured cascade. Used by the global Utf8 dictionary path where the values
     /// segment must be flat varbin — the cascade would otherwise re-pick
-    /// {@link DictEncodingEncoder} and wrap the dictionary in another dict (which the reader
+    /// [DictEncodingEncoder] and wrap the dictionary in another dict (which the reader
     /// cannot unwrap).
     private int writeSegment(DType dtype, Object data, EncodingEncoder encodingOverride) throws IOException {
         // Non-extension nullable columns (Primitive, Utf8) wrap with MaskedEncodingEncoder here.
diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/WriteRegistry.java b/writer/src/main/java/io/github/dfa1/vortex/writer/WriteRegistry.java
index 8127b2c1..2a4aa85a 100644
--- a/writer/src/main/java/io/github/dfa1/vortex/writer/WriteRegistry.java
+++ b/writer/src/main/java/io/github/dfa1/vortex/writer/WriteRegistry.java
@@ -9,7 +9,7 @@
 import java.util.Map;
 import java.util.ServiceLoader;
 
-/// Write-side registry: maps {@link EncodingId} to {@link EncodingEncoder} implementations,
+/// Write-side registry: maps [EncodingId] to [EncodingEncoder] implementations,
 /// and {@link ExtensionId} to {@link ExtensionEncoder} implementations.
 ///
 /// Instances are immutable after construction. Build one via {@link #builder()} or via the
@@ -31,7 +31,7 @@ private WriteRegistry(Map<EncodingId, EncodingEncoder> encoders,
         this.extensions = Map.copyOf(extensions);
     }
 
-    /// Loads all service-discovered {@link EncodingEncoder} and {@link ExtensionEncoder} implementations.
+    /// Loads all service-discovered [EncodingEncoder] and [ExtensionEncoder] implementations.
     ///
     /// @return an immutable {@link WriteRegistry} populated with all service-loaded entries
     public static WriteRegistry loadAll() {
@@ -40,19 +40,19 @@ public static WriteRegistry loadAll() {
 
     /// Creates an empty registry with no encoders or extensions registered.
     ///
-    /// @return a new empty immutable {@link WriteRegistry}
+    /// @return a new empty immutable [WriteRegistry]
     public static WriteRegistry empty() {
         return builder().build();
     }
 
-    /// Returns a new {@link Builder}.
+    /// Returns a new [Builder].
     ///
     /// @return a fresh builder
     public static Builder builder() {
         return new Builder();
     }
 
-    /// Returns the encoder map for use in {@link io.github.dfa1.vortex.writer.encode.EncodeContext}.
+    /// Returns the encoder map for use in [io.github.dfa1.vortex.writer.encode.EncodeContext].
     ///
     /// @return immutable encoder map
     public Map<EncodingId, EncodingEncoder> encoderMap() {
@@ -62,12 +62,12 @@ public Map<EncodingId, EncodingEncoder> encoderMap() {
     /// Returns the registered extension encoder for `extensionId`, or `null` if not registered.
     ///
     /// @param extensionId the extension id to look up
-    /// @return the registered {@link ExtensionEncoder}, or `null`
+    /// @return the registered [ExtensionEncoder], or `null`
     public ExtensionEncoder lookup(ExtensionId extensionId) {
         return extensions.get(extensionId);
     }
 
-    /// Builder for {@link WriteRegistry}.
+    /// Builder for [WriteRegistry].
     ///
     /// Not thread-safe. Build once, use everywhere — the produced {@link WriteRegistry} is immutable.
     public static final class Builder {
@@ -80,7 +80,7 @@ private Builder() {
 
         /// Registers an encoder.
         ///
-        /// @param encoder the {@link EncodingEncoder} to register
+        /// @param encoder the [EncodingEncoder] to register
         /// @return this builder, for chaining
         /// @throws VortexException if an encoder for the same id is already registered
         public Builder register(EncodingEncoder encoder) {
@@ -93,7 +93,7 @@ public Builder register(EncodingEncoder encoder) {
 
         /// Registers an extension encoder.
         ///
-        /// @param extension the {@link ExtensionEncoder} to register
+        /// @param extension the [ExtensionEncoder] to register
         /// @return this builder, for chaining
         /// @throws VortexException if an extension with the same id is already registered
         public Builder register(ExtensionEncoder extension) {
@@ -104,7 +104,7 @@ public Builder register(ExtensionEncoder extension) {
             return this;
         }
 
-        /// Registers every {@link EncodingEncoder} and {@link ExtensionEncoder} discovered via
+        /// Registers every [EncodingEncoder] and [ExtensionEncoder] discovered via
         /// {@link ServiceLoader}.
         ///
         /// @return this builder, for chaining
@@ -119,7 +119,7 @@ public Builder registerServiceLoaded() {
             return this;
         }
 
-        /// Builds an immutable {@link WriteRegistry}.
+        /// Builds an immutable [WriteRegistry].
         ///
         /// @return the immutable registry
         public WriteRegistry build() {
diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/AlpEncodingEncoder.java b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/AlpEncodingEncoder.java
index 52e00564..b87cea42 100644
--- a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/AlpEncodingEncoder.java
+++ b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/AlpEncodingEncoder.java
@@ -30,7 +30,7 @@ public final class AlpEncodingEncoder implements EncodingEncoder {
     // include drift-triggering values, letting the search penalise such combinations correctly.
     private static final int SAMPLE_SIZE = 512;
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public AlpEncodingEncoder() {
     }
 
diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/AlpRdEncodingEncoder.java b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/AlpRdEncodingEncoder.java
index dfa0b67f..fd28f841 100644
--- a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/AlpRdEncodingEncoder.java
+++ b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/AlpRdEncodingEncoder.java
@@ -23,7 +23,7 @@ public final class AlpRdEncodingEncoder implements EncodingEncoder {
     private static final int MAX_CUT = 16;
     private static final int MAX_DICT_SIZE = 8;
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public AlpRdEncodingEncoder() {
     }
 
diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/BitpackedEncodingEncoder.java b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/BitpackedEncodingEncoder.java
index b5b00afc..e7c0b940 100644
--- a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/BitpackedEncodingEncoder.java
+++ b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/BitpackedEncodingEncoder.java
@@ -20,7 +20,7 @@
 public final class BitpackedEncodingEncoder implements EncodingEncoder {
     private static final int[] FL_ORDER = {0, 4, 2, 6, 1, 5, 3, 7};
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public BitpackedEncodingEncoder() {
     }
 
diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/BoolEncodingEncoder.java b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/BoolEncodingEncoder.java
index 93dedd61..2f16e165 100644
--- a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/BoolEncodingEncoder.java
+++ b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/BoolEncodingEncoder.java
@@ -13,7 +13,7 @@
 /// Write-side encoder for `vortex.bool`.
 public final class BoolEncodingEncoder implements EncodingEncoder {
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public BoolEncodingEncoder() {
     }
 
diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/ByteBoolEncodingEncoder.java b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/ByteBoolEncodingEncoder.java
index 658aa23b..08133a0b 100644
--- a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/ByteBoolEncodingEncoder.java
+++ b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/ByteBoolEncodingEncoder.java
@@ -9,7 +9,7 @@
 /// Write-only encoder for `vortex.bytebool` — one byte per boolean element.
 public final class ByteBoolEncodingEncoder implements EncodingEncoder {
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public ByteBoolEncodingEncoder() {
     }
 
diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/CascadeStep.java b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/CascadeStep.java
index fbdfd1c3..2d8226f3 100644
--- a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/CascadeStep.java
+++ b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/CascadeStep.java
@@ -5,7 +5,7 @@
 
 /// One step in cascade-aware encoding: a partially-assembled node tree plus open child slots.
 ///
-/// Terminal steps have no open children and carry a fully-resolved {@link EncodeResult}.
+/// Terminal steps have no open children and carry a fully-resolved [EncodeResult].
 /// Intermediate steps have open children that the `CascadingCompressor` (writer module) recursively fills.
 ///
 /// Buffer layout: `ownedBuffers` holds buffers belonging to the partial root
@@ -33,7 +33,7 @@ public record CascadeStep(
     /// Convenience: terminal step — no open children, result is final.
     ///
     /// @param result the fully-resolved encode result to wrap
-    /// @return a terminal {@link CascadeStep} backed by `result`
+    /// @return a terminal [CascadeStep] backed by `result`
     public static CascadeStep terminal(EncodeResult result) {
         return new CascadeStep(result.rootNode(), result.buffers(), List.of(),
                 result.statsMin(), result.statsMax(), true);
@@ -41,7 +41,7 @@ public static CascadeStep terminal(EncodeResult result) {
 
     /// Sentinel: encoding cannot handle this data — never wins in size selection.
     ///
-    /// @return a non-applicable {@link CascadeStep} sentinel
+    /// @return a non-applicable [CascadeStep] sentinel
     public static CascadeStep notApplicable() {
         return new CascadeStep(null, List.of(), List.of(), null, null, false);
     }
@@ -54,7 +54,7 @@ public boolean isTerminal() {
     }
 
     /// Total byte size of owned buffers (used for size-based winner selection on samples).
-    /// Returns {@link Long#MAX_VALUE}/2 for non-applicable steps.
+    /// Returns [Long#MAX_VALUE]/2 for non-applicable steps.
     ///
     /// @return total size in bytes of all owned buffers, or {@link Long#MAX_VALUE}/2 if not applicable
     public long ownedBytes() {
diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/CascadingCompressor.java b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/CascadingCompressor.java
index aebbf87c..b3674b5e 100644
--- a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/CascadingCompressor.java
+++ b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/CascadingCompressor.java
@@ -13,7 +13,7 @@
 /// producing the smallest output. With `allowedCascading > 0`, also recurses
 /// into open child slots (e.g. ALP → Bitpacked for F64 columns).
 ///
-/// Encodings that override {@link EncodingEncoder#encodeCascade} expose intermediate
+/// Encodings that override [EncodingEncoder#encodeCascade] expose intermediate
 /// representations as open children; encodings that use the default are terminal.
 /// At depth 0 only terminal encodings are considered.
 public final class CascadingCompressor {
@@ -136,7 +136,7 @@ private static long primitiveBytes(DType dtype, int n) {
     /// Entry point: encode `data` using the best cascading strategy.
     ///
     /// Cascade parameters (depth, sampling, exclusions) are taken from `ctx`.
-    /// Use {@link EncodeContext#ofDepth(int, java.lang.foreign.Arena, WriteRegistry)}
+    /// Use [EncodeContext#ofDepth(int, java.lang.foreign.Arena, WriteRegistry)]
     /// to build a context with cascade depth set.
     ///
     /// @param dtype the logical type of the data to encode
diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/ChunkedData.java b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/ChunkedData.java
index 2b6e3722..3cca5914 100644
--- a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/ChunkedData.java
+++ b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/ChunkedData.java
@@ -4,7 +4,7 @@
 
 /// Input data for encoding a chunked array.
 /// Each element of `chunks` is the raw data for one chunk, in the same format
-/// the inner encoding expects (e.g. `long[]` for I64, {@link StructData} for Struct).
+/// the inner encoding expects (e.g. `long[]` for I64, [StructData] for Struct).
 /// `chunkLengths[i]` is the row count of `chunks.get(i)`.
 ///
 /// @param chunks       list of raw chunk data in the format the inner encoding expects
diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/ChunkedEncodingEncoder.java b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/ChunkedEncodingEncoder.java
index 9b7b71d7..2d98de54 100644
--- a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/ChunkedEncodingEncoder.java
+++ b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/ChunkedEncodingEncoder.java
@@ -20,7 +20,7 @@
 /// Write-only encoder for `vortex.chunked`.
 public final class ChunkedEncodingEncoder implements EncodingEncoder {
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public ChunkedEncodingEncoder() {
     }
 
diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/ConstantEncodingEncoder.java b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/ConstantEncodingEncoder.java
index 04ace22e..4ffd4ed0 100644
--- a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/ConstantEncodingEncoder.java
+++ b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/ConstantEncodingEncoder.java
@@ -11,7 +11,7 @@
 /// Write-only encoder for `vortex.constant`.
 public final class ConstantEncodingEncoder implements EncodingEncoder {
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public ConstantEncodingEncoder() {
     }
 
diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/DateExtensionEncoder.java b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/DateExtensionEncoder.java
index e0b493c0..0a06e09f 100644
--- a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/DateExtensionEncoder.java
+++ b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/DateExtensionEncoder.java
@@ -18,7 +18,7 @@ public final class DateExtensionEncoder implements ExtensionEncoder {
     /// Singleton instance.
     public static final DateExtensionEncoder INSTANCE = new DateExtensionEncoder();
 
-    /// Public no-arg constructor for {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor for [java.util.ServiceLoader].
     /// Prefer the {@link #INSTANCE} singleton in application code.
     public DateExtensionEncoder() {
     }
diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/DateTimePartsEncodingEncoder.java b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/DateTimePartsEncodingEncoder.java
index 336b83e4..35f46c9f 100644
--- a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/DateTimePartsEncodingEncoder.java
+++ b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/DateTimePartsEncodingEncoder.java
@@ -21,7 +21,7 @@ public final class DateTimePartsEncodingEncoder implements EncodingEncoder {
     private static final io.github.dfa1.vortex.proto.PType I64_PROTO =
             io.github.dfa1.vortex.proto.PType.fromValue(PType.I64.ordinal());
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public DateTimePartsEncodingEncoder() {
     }
 
diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/DecimalBytePartsEncodingEncoder.java b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/DecimalBytePartsEncodingEncoder.java
index 57136e49..7a844282 100644
--- a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/DecimalBytePartsEncodingEncoder.java
+++ b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/DecimalBytePartsEncodingEncoder.java
@@ -11,7 +11,7 @@
 /// Write-only encoder for `vortex.decimal_byte_parts`.
 public final class DecimalBytePartsEncodingEncoder implements EncodingEncoder {
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public DecimalBytePartsEncodingEncoder() {
     }
 
diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/DecimalEncodingEncoder.java b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/DecimalEncodingEncoder.java
index 04d5f67a..067e4b91 100644
--- a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/DecimalEncodingEncoder.java
+++ b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/DecimalEncodingEncoder.java
@@ -12,7 +12,7 @@
 /// Write-only encoder for `vortex.decimal`.
 public final class DecimalEncodingEncoder implements EncodingEncoder {
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public DecimalEncodingEncoder() {
     }
 
diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/DeltaEncodingEncoder.java b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/DeltaEncodingEncoder.java
index 8fe660d6..03018cdd 100644
--- a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/DeltaEncodingEncoder.java
+++ b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/DeltaEncodingEncoder.java
@@ -17,7 +17,7 @@
 /// Write-only encoder for `fastlanes.delta`.
 public final class DeltaEncodingEncoder implements EncodingEncoder {
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public DeltaEncodingEncoder() {
     }
 
diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/DictEncodingEncoder.java b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/DictEncodingEncoder.java
index 8fb7c987..96376517 100644
--- a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/DictEncodingEncoder.java
+++ b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/DictEncodingEncoder.java
@@ -20,7 +20,7 @@
 /// Write-only encoder for `vortex.dict`.
 public final class DictEncodingEncoder implements EncodingEncoder {
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public DictEncodingEncoder() {
     }
 
diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/EncodeContext.java b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/EncodeContext.java
index 857be931..88c83db3 100644
--- a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/EncodeContext.java
+++ b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/EncodeContext.java
@@ -10,7 +10,7 @@
 import java.util.HashSet;
 import java.util.Set;
 
-/// Encoding context passed to every {@link EncodingEncoder#encode} and
+/// Encoding context passed to every [EncodingEncoder#encode] and
 /// {@link EncodingEncoder#encodeCascade} call.
 ///
 /// Carries a caller-scoped {@link Arena} for encode output buffers, a
@@ -45,7 +45,7 @@ public record EncodeContext(
     ///
     /// @param arena    the arena to allocate encode output buffers from
     /// @param registry write registry for encoder and extension lookup
-    /// @return a new {@link EncodeContext} ready for non-cascading encoding
+    /// @return a new [EncodeContext] ready for non-cascading encoding
     public static EncodeContext of(Arena arena, WriteRegistry registry) {
         return new EncodeContext(arena, registry, 0, Set.of(), 42L, 4096, 0.05);
     }
@@ -55,14 +55,14 @@ public static EncodeContext of(Arena arena, WriteRegistry registry) {
     /// @param depth    maximum allowed cascade depth
     /// @param arena    the arena to allocate encode output buffers from
     /// @param registry write registry for encoder and extension lookup
-    /// @return a new {@link EncodeContext} ready for cascading compression
+    /// @return a new [EncodeContext] ready for cascading compression
     public static EncodeContext ofDepth(int depth, Arena arena, WriteRegistry registry) {
         return new EncodeContext(arena, registry, depth, Set.of(), 42L, 4096, 0.05);
     }
 
     /// Returns a copy of this context with the cascade depth decremented by one.
     ///
-    /// @return a new {@link EncodeContext} with `allowedCascading` reduced by 1
+    /// @return a new [EncodeContext] with `allowedCascading` reduced by 1
     public EncodeContext withDecrementedDepth() {
         return new EncodeContext(arena, registry, allowedCascading - 1, excluded, sampleSeed, minSampleSize, sampleFraction);
     }
@@ -70,7 +70,7 @@ public EncodeContext withDecrementedDepth() {
     /// Returns a copy of this context with the given encoding id added to the excluded set.
     ///
     /// @param id the encoding id to exclude from consideration at this recursion level
-    /// @return a new {@link EncodeContext} with `id` added to the excluded set
+    /// @return a new [EncodeContext] with `id` added to the excluded set
     public EncodeContext withExcluded(EncodingId id) {
         Set<EncodingId> next = new HashSet<>(excluded);
         next.add(id);
@@ -80,7 +80,7 @@ public EncodeContext withExcluded(EncodingId id) {
     /// Returns the encoder registered for `id`.
     ///
     /// @param id the encoding id to look up
-    /// @return the registered {@link EncodingEncoder}
+    /// @return the registered [EncodingEncoder]
     /// @throws VortexException if no encoder is registered for `id`
     public EncodingEncoder lookupEncoder(EncodingId id) {
         EncodingEncoder enc = registry.encoderMap().get(id);
diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/EncodeNode.java b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/EncodeNode.java
index d9af8ebf..a3fd560f 100644
--- a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/EncodeNode.java
+++ b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/EncodeNode.java
@@ -22,7 +22,7 @@ public record EncodeNode(
     ///
     /// @param encodingId  the encoding identifier for this leaf node
     /// @param bufferIndex index into the flat buffer list for the data buffer
-    /// @return a leaf {@link EncodeNode} referencing the given buffer
+    /// @return a leaf [EncodeNode] referencing the given buffer
     public static EncodeNode leaf(EncodingId encodingId, int bufferIndex) {
         return new EncodeNode(encodingId, null, new EncodeNode[0], new int[]{bufferIndex});
     }
@@ -31,7 +31,7 @@ public static EncodeNode leaf(EncodingId encodingId, int bufferIndex) {
     ///
     /// @param node   the root node whose buffer indices to remap
     /// @param offset the value to add to every buffer index in the subtree
-    /// @return a new {@link EncodeNode} tree with all buffer indices shifted by `offset`
+    /// @return a new [EncodeNode] tree with all buffer indices shifted by `offset`
     public static EncodeNode remapBufferIndices(EncodeNode node, int offset) {
         if (offset == 0) {
             return node;
diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/EncodeResult.java b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/EncodeResult.java
index 7d8a2aae..a8fe1374 100644
--- a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/EncodeResult.java
+++ b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/EncodeResult.java
@@ -24,7 +24,7 @@ public record EncodeResult(
     /// @param data       the single data buffer
     /// @param min        serialised minimum stat bytes, or `null`
     /// @param max        serialised maximum stat bytes, or `null`
-    /// @return an {@link EncodeResult} backed by a single-buffer leaf node
+    /// @return an [EncodeResult] backed by a single-buffer leaf node
     public static EncodeResult simple(EncodingId encodingId, MemorySegment data, byte[] min, byte[] max) {
         return new EncodeResult(EncodeNode.leaf(encodingId, 0), List.of(data), min, max);
     }
@@ -33,7 +33,7 @@ public static EncodeResult simple(EncodingId encodingId, MemorySegment data, byt
     ///
     /// @param encodingId the encoding identifier for the leaf node
     /// @param data       the single data buffer
-    /// @return an {@link EncodeResult} backed by a single-buffer leaf node with no stats
+    /// @return an [EncodeResult] backed by a single-buffer leaf node with no stats
     public static EncodeResult simple(EncodingId encodingId, MemorySegment data) {
         return simple(encodingId, data, null, null);
     }
diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/EncodingEncoder.java b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/EncodingEncoder.java
index 8fad5e4a..bd19d727 100644
--- a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/EncodingEncoder.java
+++ b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/EncodingEncoder.java
@@ -5,7 +5,7 @@
 import io.github.dfa1.vortex.core.DType;
 
 /// Write-side surface of an encoding. Exposes only the metadata required to pick an
-/// encoder for a dtype and the {@link #encode(DType, Object, EncodeContext)} entry
+/// encoder for a dtype and the [#encode(DType, Object, EncodeContext)] entry
 /// point itself.
 ///
 /// Encoder implementations live in the `writer` module and are registered via
@@ -28,7 +28,7 @@ public interface EncodingEncoder {
     EncodeResult encode(DType dtype, Object data, EncodeContext ctx);
 
     /// Cascade-aware encode: returns a partial step with open child slots.
-    /// Default wraps the terminal {@link #encode} result; override to expose children.
+    /// Default wraps the terminal [#encode] result; override to expose children.
     ///
     /// @param dtype the logical type of the data
     /// @param data  the data to encode
@@ -39,7 +39,7 @@ default CascadeStep encodeCascade(DType dtype, Object data, EncodeContext ctx) {
     }
 
     /// Stats this encoder needs from the cascade compressor's single-pass scan to evaluate
-    /// {@link #expectedRatio}. Returned options are merged across all eligible encoders so
+    /// [#expectedRatio]. Returned options are merged across all eligible encoders so
     /// one scan satisfies every consumer.
     ///
     /// @return stats requested for cascade selection; default is no stats
diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/ExtEncodingEncoder.java b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/ExtEncodingEncoder.java
index 38c5e98d..013e2daa 100644
--- a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/ExtEncodingEncoder.java
+++ b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/ExtEncodingEncoder.java
@@ -9,7 +9,7 @@
 /// Write-only encoder for `vortex.ext` — wraps a storage-array encode in an ext node.
 public final class ExtEncodingEncoder implements EncodingEncoder {
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public ExtEncodingEncoder() {
     }
 
diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/FixedSizeListEncodingEncoder.java b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/FixedSizeListEncodingEncoder.java
index c615bc1f..3459f54f 100644
--- a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/FixedSizeListEncodingEncoder.java
+++ b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/FixedSizeListEncodingEncoder.java
@@ -17,7 +17,7 @@
 /// Write-only encoder for `vortex.fixed_size_list`.
 public final class FixedSizeListEncodingEncoder implements EncodingEncoder {
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public FixedSizeListEncodingEncoder() {
     }
 
diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/FrameOfReferenceEncodingEncoder.java b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/FrameOfReferenceEncodingEncoder.java
index 80aac8e1..aaa8f15b 100644
--- a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/FrameOfReferenceEncodingEncoder.java
+++ b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/FrameOfReferenceEncodingEncoder.java
@@ -14,7 +14,7 @@
 /// Write-only encoder for `fastlanes.for` (Frame of Reference).
 public final class FrameOfReferenceEncodingEncoder implements EncodingEncoder {
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public FrameOfReferenceEncodingEncoder() {
     }
 
diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/FsstEncodingEncoder.java b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/FsstEncodingEncoder.java
index 995dfe57..1924a200 100644
--- a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/FsstEncodingEncoder.java
+++ b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/FsstEncodingEncoder.java
@@ -20,7 +20,7 @@ public final class FsstEncodingEncoder implements EncodingEncoder {
     private static final int MAX_SYMBOLS = 255;
     private static final int BIGRAM_COUNT = 65536;
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public FsstEncodingEncoder() {
     }
 
diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/LeBitWriter.java b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/LeBitWriter.java
index 5baf565c..75ed78e3 100644
--- a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/LeBitWriter.java
+++ b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/LeBitWriter.java
@@ -50,7 +50,7 @@ void alignToByte() {
         }
     }
 
-    /// Copy buffered bytes into an arena-allocated {@link MemorySegment}.
+    /// Copy buffered bytes into an arena-allocated [MemorySegment].
     ///
     /// @param arena allocator whose lifetime must exceed all uses of the returned segment
     /// @return a new segment containing every byte written so far
diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/ListEncodingEncoder.java b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/ListEncodingEncoder.java
index e076bd77..ff78afe0 100644
--- a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/ListEncodingEncoder.java
+++ b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/ListEncodingEncoder.java
@@ -20,7 +20,7 @@
 /// Write-only encoder for `vortex.list`.
 public final class ListEncodingEncoder implements EncodingEncoder {
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public ListEncodingEncoder() {
     }
 
diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/ListViewEncodingEncoder.java b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/ListViewEncodingEncoder.java
index 35345844..3d67fec2 100644
--- a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/ListViewEncodingEncoder.java
+++ b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/ListViewEncodingEncoder.java
@@ -20,7 +20,7 @@
 /// Write-only encoder for `vortex.listview`.
 public final class ListViewEncodingEncoder implements EncodingEncoder {
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public ListViewEncodingEncoder() {
     }
 
diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/MaskedEncodingEncoder.java b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/MaskedEncodingEncoder.java
index 1e914edb..d6defd3b 100644
--- a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/MaskedEncodingEncoder.java
+++ b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/MaskedEncodingEncoder.java
@@ -14,10 +14,10 @@
 import java.util.List;
 
 /// Write-only encoder for `vortex.masked`. Wraps the payload encode in a values + validity
-/// pair driven by a {@link NullableData} carrier.
+/// pair driven by a [NullableData] carrier.
 public final class MaskedEncodingEncoder implements EncodingEncoder {
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public MaskedEncodingEncoder() {
     }
 
diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/NullEncodingEncoder.java b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/NullEncodingEncoder.java
index 3c2b2e48..f5a69344 100644
--- a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/NullEncodingEncoder.java
+++ b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/NullEncodingEncoder.java
@@ -8,7 +8,7 @@
 /// Write-only encoder for `vortex.null` (all-null arrays).
 public final class NullEncodingEncoder implements EncodingEncoder {
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public NullEncodingEncoder() {
     }
 
diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/PatchedEncodingEncoder.java b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/PatchedEncodingEncoder.java
index f7e4333f..ad9dd2b0 100644
--- a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/PatchedEncodingEncoder.java
+++ b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/PatchedEncodingEncoder.java
@@ -23,7 +23,7 @@
 /// are outliers (too many patches to be worthwhile).
 public final class PatchedEncodingEncoder implements EncodingEncoder {
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public PatchedEncodingEncoder() {
     }
 
diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/PcoAnsEncoder.java b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/PcoAnsEncoder.java
index 4f9a2c92..b6c6aec7 100644
--- a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/PcoAnsEncoder.java
+++ b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/PcoAnsEncoder.java
@@ -64,7 +64,7 @@ static PcoAnsEncoder build(int sizeLog, int[] weights) {
         return new PcoAnsEncoder(sizeLog, tableSize, minR, cutoff, nextSt);
     }
 
-    /// Encode one symbol. Caller writes the low {@link Step#numBits()} bits of
+    /// Encode one symbol. Caller writes the low [Step#numBits()] bits of
     /// the old state to the bit stream (in LIFO order; caller reverses per batch).
     ///
     /// @param state  current ANS state `∈ [tableSize, 2*tableSize)`
diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/PcoEncodingEncoder.java b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/PcoEncodingEncoder.java
index e718c70a..bb0ad069 100644
--- a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/PcoEncodingEncoder.java
+++ b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/PcoEncodingEncoder.java
@@ -33,7 +33,7 @@ public final class PcoEncodingEncoder implements EncodingEncoder {
     private static final int N_BINS_LOG = 8;
     private static final int CHUNK_SIZE = 1 << 16; // 65 536 elements
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public PcoEncodingEncoder() {
     }
 
diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/PrimitiveEncodingEncoder.java b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/PrimitiveEncodingEncoder.java
index 06cd8871..3739c38e 100644
--- a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/PrimitiveEncodingEncoder.java
+++ b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/PrimitiveEncodingEncoder.java
@@ -12,7 +12,7 @@
 /// Write-only encoder for `vortex.primitive` — raw little-endian primitive arrays.
 public final class PrimitiveEncodingEncoder implements EncodingEncoder {
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public PrimitiveEncodingEncoder() {
     }
 
diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/RleEncodingEncoder.java b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/RleEncodingEncoder.java
index 14dee7f3..d808dbd2 100644
--- a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/RleEncodingEncoder.java
+++ b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/RleEncodingEncoder.java
@@ -17,7 +17,7 @@ public final class RleEncodingEncoder implements EncodingEncoder {
 
     private static final int FL_CHUNK_SIZE = 1024;
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public RleEncodingEncoder() {
     }
 
diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/RunEndEncodingEncoder.java b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/RunEndEncodingEncoder.java
index 815a36e7..788732d6 100644
--- a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/RunEndEncodingEncoder.java
+++ b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/RunEndEncodingEncoder.java
@@ -15,7 +15,7 @@
 /// Write-only encoder for `vortex.runend`.
 public final class RunEndEncodingEncoder implements EncodingEncoder {
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public RunEndEncodingEncoder() {
     }
 
diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/SequenceEncodingEncoder.java b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/SequenceEncodingEncoder.java
index 033a6ffa..3b38cfa6 100644
--- a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/SequenceEncodingEncoder.java
+++ b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/SequenceEncodingEncoder.java
@@ -13,7 +13,7 @@
 /// Write-only encoder for `vortex.sequence` — arithmetic sequences as (base, multiplier).
 public final class SequenceEncodingEncoder implements EncodingEncoder {
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public SequenceEncodingEncoder() {
     }
 
diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/SparseEncodingEncoder.java b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/SparseEncodingEncoder.java
index bafdccb7..a5b08192 100644
--- a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/SparseEncodingEncoder.java
+++ b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/SparseEncodingEncoder.java
@@ -17,7 +17,7 @@
 /// Write-only encoder for `vortex.sparse`.
 public final class SparseEncodingEncoder implements EncodingEncoder {
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public SparseEncodingEncoder() {
     }
 
diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/StructData.java b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/StructData.java
index d29235b8..99c86fa3 100644
--- a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/StructData.java
+++ b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/StructData.java
@@ -3,7 +3,7 @@
 import java.util.List;
 
 /// Input data for encoding a struct-typed column.
-/// `fieldArrays` is parallel to {@link io.github.dfa1.vortex.core.DType.Struct#fieldTypes()}.
+/// `fieldArrays` is parallel to [io.github.dfa1.vortex.core.DType.Struct#fieldTypes()].
 ///
 /// @param fieldArrays per-field data arrays in the same order as the struct's field types
 public record StructData(List<Object> fieldArrays) {
diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/StructEncodingEncoder.java b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/StructEncodingEncoder.java
index a28a533b..828e6bf4 100644
--- a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/StructEncodingEncoder.java
+++ b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/StructEncodingEncoder.java
@@ -17,7 +17,7 @@
 /// Write-only encoder for `vortex.struct`.
 public final class StructEncodingEncoder implements EncodingEncoder {
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public StructEncodingEncoder() {
     }
 
diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/TimeExtensionEncoder.java b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/TimeExtensionEncoder.java
index 82bb25e2..abbb5c3a 100644
--- a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/TimeExtensionEncoder.java
+++ b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/TimeExtensionEncoder.java
@@ -17,7 +17,7 @@ public final class TimeExtensionEncoder implements ExtensionEncoder {
     /// Singleton instance.
     public static final TimeExtensionEncoder INSTANCE = new TimeExtensionEncoder();
 
-    /// Public no-arg constructor for {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor for [java.util.ServiceLoader].
     /// Prefer the {@link #INSTANCE} singleton in application code.
     public TimeExtensionEncoder() {
     }
diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/TimestampExtensionEncoder.java b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/TimestampExtensionEncoder.java
index dabe20a3..8cd09fa9 100644
--- a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/TimestampExtensionEncoder.java
+++ b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/TimestampExtensionEncoder.java
@@ -18,7 +18,7 @@ public final class TimestampExtensionEncoder implements ExtensionEncoder {
     /// Singleton instance.
     public static final TimestampExtensionEncoder INSTANCE = new TimestampExtensionEncoder();
 
-    /// Public no-arg constructor for {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor for [java.util.ServiceLoader].
     /// Prefer the {@link #INSTANCE} singleton in application code.
     public TimestampExtensionEncoder() {
     }
diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/UuidExtensionEncoder.java b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/UuidExtensionEncoder.java
index 3f1d3496..2941c3bf 100644
--- a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/UuidExtensionEncoder.java
+++ b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/UuidExtensionEncoder.java
@@ -17,7 +17,7 @@ public final class UuidExtensionEncoder implements ExtensionEncoder {
     /// Singleton instance.
     public static final UuidExtensionEncoder INSTANCE = new UuidExtensionEncoder();
 
-    /// Public no-arg constructor for {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor for [java.util.ServiceLoader].
     /// Prefer the {@link #INSTANCE} singleton in application code.
     public UuidExtensionEncoder() {
     }
diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/VarBinEncodingEncoder.java b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/VarBinEncodingEncoder.java
index 869f3ce8..b6d7b026 100644
--- a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/VarBinEncodingEncoder.java
+++ b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/VarBinEncodingEncoder.java
@@ -16,7 +16,7 @@
 /// Write-only encoder for `vortex.varbin`.
 public final class VarBinEncodingEncoder implements EncodingEncoder {
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public VarBinEncodingEncoder() {
     }
 
diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/VarBinViewEncodingEncoder.java b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/VarBinViewEncodingEncoder.java
index 3b21a6c6..345b4070 100644
--- a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/VarBinViewEncodingEncoder.java
+++ b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/VarBinViewEncodingEncoder.java
@@ -15,7 +15,7 @@ public final class VarBinViewEncodingEncoder implements EncodingEncoder {
     private static final int MAX_INLINED_SIZE = 12;
     private static final int VIEW_SIZE = 16;
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public VarBinViewEncodingEncoder() {
     }
 
diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/VariantEncodingEncoder.java b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/VariantEncodingEncoder.java
index 34f92a82..f380637e 100644
--- a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/VariantEncodingEncoder.java
+++ b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/VariantEncodingEncoder.java
@@ -31,7 +31,7 @@ public final class VariantEncodingEncoder implements EncodingEncoder {
 
     private static final DType U64 = new DType.Primitive(PType.U64, false);
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public VariantEncodingEncoder() {
     }
 
diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/ZigZagEncodingEncoder.java b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/ZigZagEncodingEncoder.java
index de227bc5..4ef7db43 100644
--- a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/ZigZagEncodingEncoder.java
+++ b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/ZigZagEncodingEncoder.java
@@ -13,7 +13,7 @@
 /// Write-only encoder for `vortex.zigzag` — signed integers as zigzag-encoded unsigned values.
 public final class ZigZagEncodingEncoder implements EncodingEncoder {
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public ZigZagEncodingEncoder() {
     }
 
diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/ZstdEncodingEncoder.java b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/ZstdEncodingEncoder.java
index 99b2ec76..f86e475d 100644
--- a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/ZstdEncodingEncoder.java
+++ b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/ZstdEncodingEncoder.java
@@ -21,7 +21,7 @@
 /// Write-only encoder for `vortex.zstd`.
 public final class ZstdEncodingEncoder implements EncodingEncoder {
 
-    /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
+    /// Public no-arg constructor required by [java.util.ServiceLoader].
     public ZstdEncodingEncoder() {
     }
 
diff --git a/writer/src/test/java/io/github/dfa1/vortex/writer/MultiChunkUtf8RoundTripTest.java b/writer/src/test/java/io/github/dfa1/vortex/writer/MultiChunkUtf8RoundTripTest.java
index 1202dadd..968e0669 100644
--- a/writer/src/test/java/io/github/dfa1/vortex/writer/MultiChunkUtf8RoundTripTest.java
+++ b/writer/src/test/java/io/github/dfa1/vortex/writer/MultiChunkUtf8RoundTripTest.java
@@ -19,7 +19,7 @@
 
 import static org.assertj.core.api.Assertions.assertThat;
 
-/// Asserts {@link VarBinArray.ChunkedMode} fires on multi-chunk Utf8 columns.
+/// Asserts [VarBinArray.ChunkedMode] fires on multi-chunk Utf8 columns.
 ///
 /// Pre-ADR-0012-VarBin, `ScanIterator.decodeChunkedLayout` threw on
 /// `(DType.Primitive) dtype` for Utf8/Binary. This test guards the new
diff --git a/writer/src/test/java/io/github/dfa1/vortex/writer/encode/DecimalBytePartsEncodingEncoderTest.java b/writer/src/test/java/io/github/dfa1/vortex/writer/encode/DecimalBytePartsEncodingEncoderTest.java
index c7a66a2d..5691aadb 100644
--- a/writer/src/test/java/io/github/dfa1/vortex/writer/encode/DecimalBytePartsEncodingEncoderTest.java
+++ b/writer/src/test/java/io/github/dfa1/vortex/writer/encode/DecimalBytePartsEncodingEncoderTest.java
@@ -72,6 +72,6 @@ void metadata_zerothChildPtype_isI64_lowerPartCountIsZero() throws Exception {
         DecimalBytePartsMetadata meta =
                 DecimalBytePartsMetadata.decode(java.lang.foreign.MemorySegment.ofArray(metaBytes), 0, metaBytes.length);
         assertThat(meta.zeroth_child_ptype().value()).isEqualTo(7); // I64 ordinal
-        assertThat(meta.lower_part_count()).isEqualTo(0);
+        assertThat(meta.lower_part_count()).isZero();
     }
 }
diff --git a/writer/src/test/java/io/github/dfa1/vortex/writer/encode/DecodeTestHelper.java b/writer/src/test/java/io/github/dfa1/vortex/writer/encode/DecodeTestHelper.java
index 06cefb82..f96a82d5 100644
--- a/writer/src/test/java/io/github/dfa1/vortex/writer/encode/DecodeTestHelper.java
+++ b/writer/src/test/java/io/github/dfa1/vortex/writer/encode/DecodeTestHelper.java
@@ -9,7 +9,7 @@
 import java.lang.foreign.MemorySegment;
 import java.util.List;
 
-/// Utilities for wrapping encode output into a {@link DecodeContext} for round-trip tests.
+/// Utilities for wrapping encode output into a [DecodeContext] for round-trip tests.
 ///
 /// Public so writer/ test trees can reuse via the reader test-jar.
 public final class DecodeTestHelper {
@@ -17,7 +17,7 @@ public final class DecodeTestHelper {
     private DecodeTestHelper() {
     }
 
-    /// Wraps a writer's {@link EncodeResult} into a {@link DecodeContext} for round-trip assertions.
+    /// Wraps a writer's [EncodeResult] into a [DecodeContext] for round-trip assertions.
     ///
     /// @param result   writer output
     /// @param rowCount logical row count
diff --git a/writer/src/test/java/io/github/dfa1/vortex/writer/encode/EncodeTestHelper.java b/writer/src/test/java/io/github/dfa1/vortex/writer/encode/EncodeTestHelper.java
index 2c693720..7d5703dc 100644
--- a/writer/src/test/java/io/github/dfa1/vortex/writer/encode/EncodeTestHelper.java
+++ b/writer/src/test/java/io/github/dfa1/vortex/writer/encode/EncodeTestHelper.java
@@ -12,7 +12,7 @@ public final class EncodeTestHelper {
     private EncodeTestHelper() {
     }
 
-    /// Creates a non-cascading {@link EncodeContext} using a GC-managed arena and all
+    /// Creates a non-cascading [EncodeContext] using a GC-managed arena and all
     /// service-loaded {@link EncodingEncoder}s.
     ///
     /// @return a test-suitable {@link EncodeContext}
diff --git a/writer/src/test/java/io/github/dfa1/vortex/writer/encode/ExtEncodingEncoderTest.java b/writer/src/test/java/io/github/dfa1/vortex/writer/encode/ExtEncodingEncoderTest.java
index 5174df44..ec4736e6 100644
--- a/writer/src/test/java/io/github/dfa1/vortex/writer/encode/ExtEncodingEncoderTest.java
+++ b/writer/src/test/java/io/github/dfa1/vortex/writer/encode/ExtEncodingEncoderTest.java
@@ -103,7 +103,7 @@ void encodeCascade_exposesStorageAsOpenChild() {
             ChildSlot slot = result.openChildren().get(0);
             assertThat(slot.childDtype()).isEqualTo(storageDType);
             assertThat(slot.childData()).isSameAs(data);
-            assertThat(slot.parentChildIdx()).isEqualTo(0);
+            assertThat(slot.parentChildIdx()).isZero();
             assertThat(result.partialRoot().encodingId()).isEqualTo(EncodingId.VORTEX_EXT);
             assertThat(result.partialRoot().children()).hasSize(1);
         }
diff --git a/writer/src/test/java/io/github/dfa1/vortex/writer/encode/ListEncodingEncoderTest.java b/writer/src/test/java/io/github/dfa1/vortex/writer/encode/ListEncodingEncoderTest.java
index 7cb5bc10..ecef30b8 100644
--- a/writer/src/test/java/io/github/dfa1/vortex/writer/encode/ListEncodingEncoderTest.java
+++ b/writer/src/test/java/io/github/dfa1/vortex/writer/encode/ListEncodingEncoderTest.java
@@ -123,7 +123,7 @@ void roundTrip_emptyLists_preservesOffsets() {
 
             // Then
             assertThat(result.length()).isEqualTo(2);
-            assertThat(result.elements().length()).isEqualTo(0);
+            assertThat(result.elements().length()).isZero();
             assertThat(result.offsets().length()).isEqualTo(3);
         }
 
diff --git a/writer/src/test/java/io/github/dfa1/vortex/writer/encode/ListViewEncodingEncoderTest.java b/writer/src/test/java/io/github/dfa1/vortex/writer/encode/ListViewEncodingEncoderTest.java
index db8e79d7..0b323bb0 100644
--- a/writer/src/test/java/io/github/dfa1/vortex/writer/encode/ListViewEncodingEncoderTest.java
+++ b/writer/src/test/java/io/github/dfa1/vortex/writer/encode/ListViewEncodingEncoderTest.java
@@ -117,7 +117,7 @@ void roundTrip_emptyLists_preservesZeroSizes() {
 
             // Then
             assertThat(resultDecoded.length()).isEqualTo(2);
-            assertThat(resultDecoded.elements().length()).isEqualTo(0);
+            assertThat(resultDecoded.elements().length()).isZero();
             assertThat(resultDecoded.offsets().length()).isEqualTo(2);
             assertThat(resultDecoded.sizes().length()).isEqualTo(2);
         }