docs(fern): inject local library entry at generate time instead of committing it

A committed path-input library entry breaks 'fern docs dev' and
'fern generate --docs': the docs config parser rejects any
'input.path' library ("'path' input which is not yet supported.
Please use 'git' input.") and renders a blank page. Meanwhile
'fern docs md generate --local' only accepts path inputs, so the
entry can't live in docs.yml at all.

Move the nemo-curator-local entry out of docs.yml and into
scripts/generate-library-local.sh, which injects it temporarily,
runs the local generation, and restores docs.yml on exit. The npm
script and Makefile target now call the script; CI flows are
unchanged.

Verified in the fern-api/fern source and npm bundles that the parser
throw exists in 5.50.4 (our pin) and 5.65.5 (latest), and that
'fern check' does not catch it — only 'docs dev'/builds fail.

Signed-off-by: Lawrence Lane <llane@nvidia.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: lbliii

.claude/skills/nemo-curator-docs/SKILL.md

@@ -320,10 +320,10 @@ This is a temporary maneuver — track the change so it gets reverted.
 
 ## Library Reference (Autodocs) and the Fern Cross-Ref Bug
 
-`fern/docs.yml` declares two `libraries:` entries that write to the same output folder (`fern/product-docs/nemo-curator/Full-Library-Reference/`, gitignored):
+`fern/docs.yml` declares one `libraries:` entry, and a script provides a second, temporary one (both write to `fern/product-docs/nemo-curator/Full-Library-Reference/`, gitignored):
 
-- **`nemo-curator`** (`input.git`) — used by CI/publish/preview; requires `fern login` or `FERN_TOKEN`. Workflows run `fern docs md generate --library nemo-curator`.
-- **`nemo-curator-local`** (`input.path: ../nemo_curator`) — local dev without Fern auth; requires Docker. Run `npm run generate:library:local` from `fern/`.
+- **`nemo-curator`** (`input.git`, committed in `docs.yml`) — used by CI/publish/preview; requires `fern login` or `FERN_TOKEN`. Workflows run `fern docs md generate --library nemo-curator`.
+- **`nemo-curator-local`** (`input.path: ../nemo_curator`, injected temporarily by `fern/scripts/generate-library-local.sh`) — local dev without Fern auth; requires Docker. Run `npm run generate:library:local` from `fern/`. The entry must NOT be committed to `docs.yml`: `fern docs dev` rejects path-input libraries ("'path' input which is not yet supported") and renders a blank page, while `--local` generation only accepts `path` inputs.
 
 For a full API reference locally (424 pages), use `npm run generate:library`. The local Docker parser is beta and currently produces fewer pages — fine for testing the no-auth flow, not a substitute for CI generation.
 

Makefile

@@ -45,7 +45,7 @@ docs-generate-library:
 
 docs-generate-library-local:
 	@echo "Generating Python API reference locally under $(FERN_DIR)/product-docs/ (Docker; no Fern auth)..."
-	cd $(FERN_DIR) && $(FERN) docs md generate --local --library nemo-curator-local
+	bash $(FERN_DIR)/scripts/generate-library-local.sh
 
 docs-substitute:
 	@echo "Substituting {{ variables }} in versions/v$(DOCS_VERSION) MDX..."

fern/AUTODOCS_GUIDE.md

@@ -92,9 +92,11 @@ fern docs md generate --library nemo-curator
 For local generation without Fern authentication (requires Docker):
 
 ```bash
-fern docs md generate --local --library nemo-curator-local
+npm run generate:library:local   # runs scripts/generate-library-local.sh
 ```
 
+The script temporarily injects a path-input `nemo-curator-local` entry into `docs.yml`, runs `fern docs md generate --local`, and restores `docs.yml`. The entry cannot be committed: `fern docs dev` rejects any `input.path` library and renders a blank page, while `--local` generation only accepts `path` inputs.
+
 Fern will generate markdown under the output path you configured, for example:
 
 ```text

fern/README.md

@@ -99,14 +99,13 @@ For prose-only iteration, `fern docs dev` is enough. Library reference (`product
 
 ### Library reference without Fern login
 
-CI and deploy previews use the `nemo-curator` library (`input.git`) and require `fern login` or `FERN_TOKEN`. For local iteration on the Python API reference without Fern authentication, use the `nemo-curator-local` entry (`input.path`) with Docker:
+CI and deploy previews use the `nemo-curator` library (`input.git`) and require `fern login` or `FERN_TOKEN`. For local iteration on the Python API reference without Fern authentication, run:
 
 ```bash
-npm run generate:library:local
-# equivalent: fern docs md generate --local --library nemo-curator-local
+npm run generate:library:local   # runs scripts/generate-library-local.sh; requires Docker
 ```
 
-Both libraries write to the same output folder (`product-docs/nemo-curator/Full-Library-Reference`), so previews and publish keep working unchanged. Requires Docker (Fern pulls `fernapi/fern-python-library-docs-parser` on first run).
+The script temporarily injects a path-input `nemo-curator-local` entry into `docs.yml`, runs `fern docs md generate --local --library nemo-curator-local`, and restores `docs.yml` afterward. The entry can't live in the committed `docs.yml`: `fern docs dev` and `fern generate --docs` reject any `input.path` library ("'path' input which is not yet supported") and render a blank page, while `--local` generation only accepts `path` inputs. Both flows write to the same output folder (`product-docs/nemo-curator/Full-Library-Reference`), so previews and publish keep working unchanged. Requires Docker (Fern pulls `fernapi/fern-python-library-docs-parser` on first run).
 
 ### Variable substitution
 
@@ -220,7 +219,8 @@ PR titles follow Conventional Commits (e.g. `docs(fern): add rollout collection
 | Symptom | Fix |
 |---|---|
 | `HTTP 403: User does not belong to organization` on library generation | Sign in to https://dashboard.buildwithfern.com first, then re-run `fern login`. Or use `npm run generate:library:local` (no Fern auth; requires Docker). |
-| `Folder not found: ./product-docs/...` in `fern docs dev` | Library generation hasn't run; trigger a `fern docs dev` cycle or check the `libraries:` block in `docs.yml` |
+| `Folder not found: ./product-docs/...` in `fern docs dev` | Library generation hasn't run; run `npm run generate:library` (or `generate:library:local`) first |
+| `Library '...' uses 'path' input which is not yet supported` + blank page in `fern docs dev` | A path-input library entry is committed in `docs.yml` — remove it; local generation injects it temporarily via `scripts/generate-library-local.sh` |
 | `fern check` YAML error | 2-space indent; `- page:` inside `contents:`; `path:` is relative to the version YAML |
 | Page 404 in preview | `slug:` missing/duplicated in the same section, or `position:` collision in an auto-discovered folder |
 | Broken-link warning for cross-version path | False positive in `fern docs dev`; the published site resolves it correctly |

fern/docs.yml

@@ -183,12 +183,11 @@ libraries:
     output:
       path: ./product-docs/nemo-curator/Full-Library-Reference
     lang: python
-  nemo-curator-local:
-    input:
-      path: ../nemo_curator
-    output:
-      path: ./product-docs/nemo-curator/Full-Library-Reference
-    lang: python
+  # NOTE: do not add a path-input library entry here. `fern docs dev` and
+  # `fern generate --docs` reject any `input.path` library ("'path' input
+  # which is not yet supported") and render a blank page. Local no-auth
+  # generation injects a temporary path entry via
+  # scripts/generate-library-local.sh instead.
 
 experimental:
   mdx-components:

fern/package.json

@@ -7,7 +7,7 @@
     "dev": "npx -y fern-api@latest docs dev",
     "generate": "npx -y fern-api@latest generate --docs",
     "generate:library": "npx -y fern-api@latest docs md generate --library nemo-curator",
-    "generate:library:local": "npx -y fern-api@latest docs md generate --local --library nemo-curator-local"
+    "generate:library:local": "bash scripts/generate-library-local.sh"
   },
   "engines": {
     "node": ">=20"

fern/scripts/generate-library-local.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# Generate the Python API reference locally, without Fern auth (requires Docker).
+#
+# Why the temporary docs.yml edit: the Fern CLI has two conflicting rules —
+#   * `fern docs md generate --local` only accepts libraries with a `path` input
+#     (git inputs are generated remotely and need auth), but
+#   * `fern docs dev` / `fern generate --docs` refuse to parse a docs.yml that
+#     contains any `path` input library ("'path' input which is not yet
+#     supported. Please use 'git' input.") and render a blank page.
+#
+# So the path-based entry cannot live in the committed docs.yml. This script
+# injects it, runs local generation, and restores docs.yml on exit.
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+LIBRARY_NAME="nemo-curator-local"
+SOURCE_PATH="../nemo_curator"
+OUTPUT_PATH="./product-docs/nemo-curator/Full-Library-Reference"
+
+if ! grep -q '^libraries:' docs.yml; then
+  echo "error: no 'libraries:' block found in docs.yml" >&2
+  exit 1
+fi
+if grep -q "^  ${LIBRARY_NAME}:" docs.yml; then
+  echo "error: docs.yml already contains '${LIBRARY_NAME}' — remove it; a committed path-input entry breaks 'fern docs dev'" >&2
+  exit 1
+fi
+
+cp docs.yml docs.yml.bak
+trap 'mv docs.yml.bak docs.yml' EXIT
+
+awk -v lib="$LIBRARY_NAME" -v src="$SOURCE_PATH" -v out="$OUTPUT_PATH" '
+  1
+  /^libraries:/ {
+    print "  " lib ":"
+    print "    input:"
+    print "      path: " src
+    print "    output:"
+    print "      path: " out
+    print "    lang: python"
+  }
+' docs.yml.bak > docs.yml
+
+npx -y "fern-api@$(node -p 'require("./fern.config.json").version')" \
+  docs md generate --local --library "$LIBRARY_NAME"