fix(api-docs): preserve manual content during generation

[Piotr1215]

Summary

Stop generating main API resource pages (platform/api/resources/*.mdx). Only generate partials (platform/api/_partials/resources/*/).

Problem

Automated API docs generation (loft-bot PRs) overwrites manually-added documentation sections in platform API resource files:

• clusterroletemplate.mdx - Policy rules section
• clusters.mdx - Platform-specific verbs section
• team.mdx - Platform-specific verbs section
• user.mdx - Platform-specific verbs section

Solution

Follow the vcluster pattern: partials are auto-generated, main pages are manually maintained.

Technical Details

What the generator does NOW (after this PR)

When go run ./hack/platform/partials/main.go runs:

1. Deletes platform/api/_partials/resources/ directory (line 30 in main.go)
2. Regenerates all partials:
   • _partials/resources/<resource>/reference.mdx - schema reference docs
   • _partials/resources/<resource>/create.mdx - create examples (if enabled)
   • _partials/resources/<resource>/retrieve.mdx - retrieve examples (if enabled)
   • _partials/resources/<resource>/update.mdx - update examples (if enabled)
   • _partials/resources/<resource>/delete.mdx - delete examples (if enabled)
3. Does NOT touch main page files in platform/api/resources/

What the generator did BEFORE (the problem)

Same as above, but also:

• Overwrote main page files (resources/<resource>.mdx) using TemplateObjectOverview template
• This destroyed any manually-added content

Code changes

hack/platform/util/schema.go:

• Removed the writeTemplate(TemplateObjectOverview, ...) call at the end of GenerateObjectOverview()
• Removed the relPath calculation that was only used for main page generation
• Added comment explaining main pages are manually maintained

hack/platform/util/template_overview.go:

• Deleted entirely - contained TemplateObjectOverview and ObjectOverviewValues which are no longer used

How main pages work

Main pages import and render the auto-generated partials:

// platform/api/resources/clusterroletemplate.mdx
import Reference from "../_partials/resources/clusterroletemplates/reference.mdx"
import Create from "../_partials/resources/clusterroletemplates/create.mdx"

// ... manual content like Policy rules section ...

<Reference />
<Create />

When schema changes:

1. Generator regenerates partials with new schema
2. Main pages automatically show updated content via imports
3. Manual sections remain untouched

Impact on existing workflow

Scenario	Before	After
Schema update	Partials + main pages regenerated	Only partials regenerated
Manual content	Lost on regeneration	Preserved
New resource added	Main page auto-created	Must manually create main page

What happens for NEW resources?

When adding a new resource to main.go:

1. Partials are generated in _partials/resources/<new-resource>/
2. No main page is created - developer must manually create resources/<new-resource>.mdx
3. Main page should import and render the partials, plus any custom content

Verified behavior

Ran generator and confirmed:

• _partials/resources/clusterroletemplates/reference.mdx - regenerated (timestamp updated)
• _partials/resources/clusterroletemplates/create.mdx - regenerated (timestamp updated)
• resources/clusterroletemplate.mdx - untouched (timestamp unchanged, git diff empty)

Note on unused File field

The ObjectInformation.File field is still passed from main.go but is now ignored. This could be cleaned up in a follow-up PR but is harmless.

Testing

• go build ./hack/platform/... passes
• Ran generator - partials regenerated, main pages untouched
• Existing main pages have correct imports to partials

Closes DOC-1196

[netlify]

✅ Deploy Preview for vcluster-docs-site ready!

Name	Link
🔨 Latest commit	fe2fb7e
🔍 Latest deploy log	https://app.netlify.com/projects/vcluster-docs-site/deploys/6981c693e4c165000865a80c
😎 Deploy Preview	https://deploy-preview-1663--vcluster-docs-site.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

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

[loft-bot]

Claude finished @Piotr1215's task in 35s —— View job

---

No issues found. The file existence check using os.Stat() is correctly implemented and the early return prevents overwriting existing files as intended.

[github-actions]

DOC-1196: preserve manual doc sections during api docs generation