docs(docusaurus): move version dropdown to left navbar; shorten label to 'main'

[planetf1]

What and why

1. Navbar version dropdown position

The version dropdown currently sits on the right side of the navbar, between Community and GitHub:

Docs | API Reference — — — Blog | Community | main ▾ | GitHub | mellea.ai

That position is confusing — it looks like an external link rather than a navigation control for the docs content. This PR moves it to the left side, immediately after API Reference:

Docs | API Reference | Next ▾ — — — Blog | Community | GitHub | mellea.ai

2. Version label: use Docusaurus default

Rather than an explicit label, the current version block now relies on Docusaurus's built-in default label (Next). This:

• avoids ambiguity ("main" on its own reads as a menu category, not a version)
• matches the Docusaurus ecosystem convention for unreleased versions
• simplifies the release pipeline: set-last-version.mjs previously injected path: 'main' into the config on first release; with no explicit label or path set, Docusaurus routes the current version to /next/ automatically, so that injection step is no longer needed

3. CLI reference page removed

The auto-generated CLI reference page (reference/cli) has been removed from the sidebar and its Mintlify-era redirect rules removed from the config. In-page cross-links in the how-to and integration docs updated to point to the API Reference instead.

4. PUBLISHING.md: stale label refs + fork preview docs

• Updates references to 'main (unreleased)' that would have become stale.
• Expands the brief fork PR warning into a full "Previewing from your own fork" section, covering the GitHub Pages bootstrap pattern (including the docs/staging workaround needed when gh-pages doesn't exist yet) and the fork baseUrl difference (/mellea/ vs /).

Notes

The build-and-validate CI job builds the full Docusaurus site on every PR touching docs/, so any config error would be caught before merge.

[ajbozarth]

could you include before and after screen shots?

[planetf1]

It's a minor change to the wording of 'main' (removing unreleased) and moving it after the first main links. It will be more obvious after our release as it will then inherit the correct release name. In the current published version it's in the middle of other links. So a very small change - maybe we could do more, but I think it's an improvement
ok @ajbozarth ?

[psschwei]

I think it's a good fix, though should we have something like 'version: main` to call out that it's the version? the word main by itself is a bit ambiguous

[planetf1]

I think it's a good fix, though should we have something like 'version: main` to call out that it's the version? the word main by itself is a bit ambiguous

The default for docusaurus is actually 'Next' - something other sites use. We also have to be careful as some of the code in docusaurus relates to the filesystem structure (ie the top level directory). next is acually the default here - so I'm now thinking let's just leave at the pure default...

It will become clearer after a release

[ajbozarth]

Two of the three changes here look good (navbar move, label/banner/set-last-version.mjs cleanup). The CLI-reference removal has loose ends that I think warrant splitting it out:

• The generator still writes the page: pyproject.toml defines clidocs / clidocs-clean poe tasks, tooling/docs-autogen/generate_cli_reference.py still emits docs/docs/reference/cli.md, and tooling/docs-autogen/generate-ast.py:776 still inserts See the [CLI Reference](/reference/cli) into the auto-generated API landing. After this PR the landing page will link to something not in any sidebar.
• docs/CONTRIBUTING_DOCS.md:481 still uses [CLI Reference](../reference/cli) as the canonical "See also" example.
• The 17 /api/cli/... redirect entries are removed, but the destination (/reference/cli) is also being de-listed — anyone with bookmarks to either path 404s.

Suggest splitting into:

1. Navbar move + label/banner/set-last-version.mjs cleanup + PUBLISHING.md updates (LGTM after the small fixes below)
2. CLI reference removal as a separate PR that also handles the generator, ast link, CONTRIBUTING_DOCS example, and a deliberate decision on the redirects

A couple of smaller things:

• Title nit: "shorten label to 'main'" is stale — the final implementation uses the Docusaurus default (Next), which is the cleaner way to drop the verbose (unreleased). Worth updating to something like use Docusaurus default version label so the title matches what landed.
• Could you also refresh the screenshots in the PR description? Both the before/after blockquotes and the attached images still show main ▾, but the dropdown now renders as Next ▾.

[ajbozarth]

LGTM for now, I ran it locally and the Next could be a bit confusing, but it's only for another couple weeks so I think it's fine

[planetf1]

the cli changes were an error - lingering changes left on the branch. not intended for here