Overture docs V2 update

[MitchellShiell]

Overture docs site v2: restructure into Develop / Deploy / Use / Community

Rebuilds the documentation site around four audience-facing sections, replaces the old docs / guides / workshop split, adds the deployment and AI-assisted data discovery guides, and ships three interactive in-page tools. Component reference docs are pulled in from the submodules/ doc branches, so this PR is blocked on
the submodule PRs in the table below.

overtureDocsUpdate -> main · 16 commits · 185 files (+13,787 / -10,069) plus 7 submodule pin bumps.

⚠️ Blocked on submodule merges

Every component's reference docs live in its own repo and are vendored here as a submodule. This PR's pins currently point at branch tips that are not yet on their default branches. Each row must be merged first, then the pin re-pointed at the resulting default-branch commit before this PR can go in.

Component	Submodule path	Repo	Branch to merge	Target branch	Commits	Doc files	Pinned commit here
Lectern	submodules/lectern	overture-stack/lectern	overtureDocsUpdate	main	5	10	ca2aa45
Lyric	submodules/lyric	overture-stack/lyric	overtureDocsUpdate	main	4	5	181bbb1
Song	submodules/song	overture-stack/song	overtureDocsUpdate	develop	5	18	28a01d6a
Score	submodules/score	overture-stack/score	overtureDocsUpdate	develop	2	9	38386151
Maestro	submodules/maestro	overture-stack/maestro	overtureDocsUpdate	master	5	13	79da1a4
Arranger	submodules/arranger	overture-stack/arranger	overtureMCPdocsUpdate	main	4	15	008d98b9
Stage	submodules/stage	overture-stack/stage	overtureDocsUpdate	main	2	1	580d785

All seven branches are pushed and have no unpushed or uncommitted work.

Note on Arranger: its branch is overtureMCPdocsUpdate, not overtureDocsUpdate.
It predates the naming convention and was left as is rather than renamed.

What changed in this repo

Information architecture

The site moves from docs / guides / workshop / community to four audience-oriented Docusaurus plugin instances, each with its own sidebar:

Route	Content path	Sidebar	Audience
/develop	website/docs/develop-docs	developSidebars.ts	Component internals, API reference, contributing
/deploy	website/docs/deploy-docs	deploySidebars.ts	Standing up a platform
/use	website/docs/use-docs	useSidebars.ts	Submitting, retrieving, administering, workshop
/community	website/docs/community-docs	communitySidebars.ts	Support, team, funding, licensing, conduct

sidebars.ts, guidesSidebars.ts, workshopSidebars.ts and casestudiesSidebars.ts
are removed. Navbar becomes Develop / Deploy / Use.

New content

• Deployment guides (/deploy/deployment): per-component walkthroughs: Keycloak, Song, Score, Lectern, Lyric, search engine, Maestro, Arranger, Stage, plus file transfer, search portal, tabular data submission, and the Arranger MCP server.
• AI-assisted data discovery (/use/ai-assisted-data-discovery): testing environment, connecting a host, configuration templates, use cases, and deploying your own MCP server.
• Administration guides (/use/administration): building dictionaries, building Song schemas, customizing the data portal, index mappings.
• API reference (/develop/api-reference): per-component Swagger pages for Song, Score, Maestro, Lyric, Lectern and Arranger. lecternAPI.json added; the Song, Score, Maestro and Lyric specs are regenerated against current code.
• The IBC Workshop has been generalized and moved under /use/workshop with a new generalized intro page.

Interactive components

Three browser-only tools, each with a docs page under /use/config-generators-and-playgrounds:

• ConfigGenerator: upload a flat CSV, infer types, and emit a Lectern dictionary, Song schema, Elasticsearch/opensearch mapping, Arranger configs and a Postgres table. Limitations on making configs for hierarchical data is presented on the page, this is here and crosslinked to complement the workshop.
• DictionaryPlayground: live Lectern dictionary authoring and validation with lectern viewer component generation
• SongSchemaPlayground: live Song schema authoring and validation (requiring some reworking).

Build and dependencies

• Docusaurus 3.9.2 to 3.10.2; package renamed bridge-poc to overture-docs.
• Adds @overture-stack/lectern-dictionary, @overture-stack/lectern-ui, the CodeMirror editor stack, and @docusaurus/plugin-client-redirects.
• website/docsPlugin.ts gains webpack config to make the Lectern viewer bundle for the browser: aliases d3-dag to its ESM build (its CJS build pulls in Node built-ins), stubs Node core modules, rewrites node:-scheme imports, and silences the resulting d3-dag critical-dependency warning.
• react/react-dom pinned via overrides for @overture-stack/lectern-ui.

Merge order

1. Open and merge the seven submodule doc PRs in the table above.
2. In each submodule, fetch and check out the merge commit on the default branch.
3. Bump the seven pins in this branch, commit, push.
4. Re-run the site build and confirm every submodule-sourced page still resolves.
5. Merge this PR.

Verification

• npm ci && npm run build in website/ is clean
• No broken links reported by the Docusaurus build
• Every legacy URL in the redirect list resolves
• The three interactive tools render and run in a production build
• All seven pins point at commits reachable from their default branches

[netlify]

✅ Deploy Preview for overturedocs ready!

Name	Link
🔨 Latest commit	020a95f
🔍 Latest deploy log	https://app.netlify.com/projects/overturedocs/deploys/6a6a9216f8e2210008b6c987
😎 Deploy Preview	https://deploy-preview-48--overturedocs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.