Retire the hand-maintained NebariApp field reference

[dcmcand]

Second half of item 3 of the implementation outline in
RFD #59, accepted 2026-09-10. The
specification itself is nebari-dev/nebari-operator#187.

Refs nebari-dev/governance#59

What I found

RFD #59 §6 says the Pack Specification should live with the operator so the contract and its
implementation version together, and calls the copy here stale. It is worse than that.

This repository carried two hand-maintained copies of the same 17.8KB field reference:

• docs/nebariapp-crd-reference.md
• docs/site/src/content/docs/nebariapp-crd-reference.md

They differ only in frontmatter, one using an H1 and the other Starlight's title:. There is
no script or CI step keeping them in step, so they were being edited by hand in parallel. The
operator generates a third copy from the Go types via make docs.

Both copies declare **Operator version this doc tracks:** v0.1.0-alpha.19 and had fallen
behind. Nothing detects that, which is the whole argument for not keeping a contract in a
different repository from the code that enforces it.

What changed

The page stays, at the same slug and title, and now says where the contract and the field
reference live. Keeping the URL matters: it is a published page on the docs site, it is
linked from four other site pages, and docs/site/test/build.test.ts asserts it exists with
that exact title. Deleting it would have changed the published site structure and broken the
test for no benefit.

The field tables and status/condition tables are gone. Both are maintained better elsewhere:
fields in the operator's generated api-reference.md, reconciler behavior in the operator's
docs/reconcilers/.

What the page indexes instead is what this repository is actually for, worked examples:
vanilla-yaml, basic-nginx, kustomize-nginx, wrap-existing-chart, and auth-fastapi.

Nine inbound references also updated

Every place that promised a complete field reference this page no longer holds:

File	Was
README.md (3)	a tree comment calling it the "Full NebariApp field reference", plus two "complete field reference" pointers
docs/auth-flow.md (2)	"the fields documented in nebariapp-crd-reference.md"
docs/site/.../build-your-own.md	"every field explained"
docs/site/.../index.md	"complete field-by-field reference"
docs/site/.../what-is-a-software-pack.md	"for the full field list"
docs/site/.../auth-flow.md	"the fields documented in the NebariApp CRD Reference"

Each now points at the generated reference or the specification. Leaving them would have been
worse than the original problem: links promising a full reference and landing on a stub.

Testing

Using the toolchain CI uses, bun:

• bun install --frozen-lockfile && bun run build succeeds. All 8 pages build, including
  /nebariapp-crd-reference/index.html.
• bun test test: 10 pass, 1 fail. The failure is
  Nebari branding: magenta accent, Space Grotesk headings, footer, portal logo link,
  asserting data-nebari-footer on the home page. It fails identically on pristine main
  with my changes stashed, so it is pre-existing and not something this PR introduces. Worth
  someone looking at separately, since it means the branding test has been red.
• The page-existence and title assertions that cover this page pass.
• lint.yaml validates Helm and kustomize manifests only, and this change is markdown.

Reviewer call

I took the least destructive reading of "retire the duplicate": keep the page and its URL,
strip the duplicated content, point at the source of truth. The alternative is deleting the
page, updating the sidebar and the test, and accepting a changed site structure. If you would
rather the page go away entirely, say so and I will do that instead.

[github-actions]

📄 Docs preview for dcmcand/rfd-59-retire-crd-reference:
https://dcmcand-rfd-59-retire-crd-re.nebari-software-pack-template.pages.dev

[dcmcand]

Superseded by #45 (a26aa28), which retires the hand-maintained field and status tables and repoints the inbound references as this PR proposed. Two differences: the page keeps the namespace opt-in, OIDC Secret, and deployment-pattern sections, which have no home in the operator docs, and it holds the Pack Specification links until nebari-dev/nebari-operator#187 merges. It also keeps the auth.groups not-enforced warning, since the generated v0.1.1 reference still describes groups as access control.