## TL;DR
Allow the tag with -Xdoclint, add it via -tag apiNote:a, or disable the missing-tag check. The cleanest long-term fix is upgrading the JDK, since apiNote is standard in newer releases. Verify the build passes with -Werror.

## The exact error
```text
error: unknown tag: apiNote
```

## Steps
1. **Confirm the JDK version**
   Run javac -version and javadoc -version. JDK 8 doclint rejects tags it does not know, including apiNote.
   Success check: You know the exact JDK running the build.
2. **Declare the custom tag**
   Pass -tag 'apiNote:a:API Note:' to javadoc so doclint accepts the tag as valid.
   Success check: The tag is declared and the error moves or disappears.
3. **Or relax doclint**
   Use -Xdoclint:none to disable doclint, or -Xdoclint:-missing to keep checks but allow unknown tags. Prefer the narrowest relaxation.
   Success check: The build passes with the minimal doclint change.
4. **Verify with -Werror**
   Run the full javadoc build with -Werror and confirm zero errors.
   Success check: Clean javadoc build with errors promoted and none remaining.

## When to use
- Use when JDK 8 javadoc rejects apiNote, implSpec, or implNote tags.
- Use when a project must stay on JDK 8 but uses newer documentation tags.

## When not to use
- Not for 'reference not found' errors (link resolution, not tag allowlisting).
- Not for HTML errors in comments (different doclint check).

## Why it happens
JDK 8 enabled doclint by default with -Werror in many builds, and its tag list predates apiNote. Code written against newer JDK conventions fails on the older toolchain even though the tags are legitimate.

## Edge cases
Upgrading the JDK is the durable fix; doclint relaxations are stopgaps that hide other documentation problems. If the project documents against multiple JDKs, gate the -tag flags on the JDK version in the build script.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_NIOl3fYUP3RZriPKo1w2_Q