Migrate calm-studio docs-site into main documentation site

[rocketstack-matt]

Feature Proposal

Target Project:

calm-suite/calm-studio (docs-site) and docs

Description of Feature:

calm-studio has its own standalone Docusaurus documentation site at calm-suite/calm-studio/docs-site/. The main monorepo already has a Docusaurus documentation site at docs/ which serves as the unified home for all CALM project documentation at calm.finos.org. The calm-studio documentation should be migrated into the main docs site for consistency and discoverability.

User Stories:

• As a user, I want to find all CALM documentation in one place (calm.finos.org) rather than across separate sites
• As a maintainer, I want a single docs build pipeline rather than managing separate Docusaurus instances
• As a contributor, I want consistent documentation structure across all projects

Current Limitations:

• calm-studio docs live in a separate Docusaurus site (calm-suite/calm-studio/docs-site/) that is not deployed anywhere in the monorepo
• The docs-site has a webpack ProgressPlugin compatibility issue that causes build failures
• The docs-site includes TypeDoc API reference generation from @calmstudio/calm-core which would need to be integrated into the main docs build
• Having two Docusaurus sites in the same repo creates confusion about which to maintain

Proposed Implementation:

1. Review the calm-studio docs-site content and identify pages to migrate
2. Create a calm-suite/ section in the main docs/ Docusaurus site
3. Migrate markdown content from calm-suite/calm-studio/docs-site/docs/ to docs/docs/calm-suite/
4. Integrate TypeDoc API reference generation for @calmstudio/calm-core into the main docs build (or link to separately published API docs)
5. Add sidebar entries for CALM Guard and CALM Studio documentation
6. Remove calm-suite/calm-studio/docs-site/ once migration is complete
7. Remove the docs.yml workflow reference (already removed from .github/)

Alternatives Considered:

• Keep the separate docs-site and deploy it independently — fragments the documentation, harder to maintain
• Only link to external docs — loses the benefit of unified search and navigation

Testing Strategy:

• Build the main docs site with the new content: npm run build --workspace=docs
• Verify all calm-studio documentation renders correctly
• Verify TypeDoc API references are accessible
• Check for broken links

Documentation Requirements:

• This issue IS the documentation work

Implementation Checklist:

• Audit calm-studio docs-site content
• Create calm-suite section in main docs
• Migrate markdown content
• Integrate or link API reference docs
• Update sidebar navigation
• Remove calm-suite/calm-studio/docs-site/
• Verify docs build passes
• Check for broken links

Additional Context:

The calm-studio docs-site was part of the standalone calmstudio repository before it was brought into the monorepo via #2320 / #2329. The docs-site build currently has a webpack ProgressPlugin compatibility issue with Docusaurus 3.9 that causes build failures even on Node 22.

[markscott-ms]

I suggest we resolve #2318 / #2319 before agreeing to progress with this issue, as these may impact how documentation is stored and maintained across the CALM ecosystem

[gjs-opsflo]

I can migrate the docs to the main docusaurus. Do I wait till #2318 / #2319 is resolved, or start on this, @rocketstack-matt ?

[markscott-ms]

Looks like they are resolving to a situation where it won’t matter, so you could start.