Migrate documentation to Fumadocs and verify MCSS 13.10.0 workflows

.dockerignore

@@ -0,0 +1,8 @@
+.git
+node_modules
+.next
+.source
+out
+docs/apis/v1
+docs/apis/v2
+*.tsbuildinfo

.github/workflows/deploy.yml

@@ -1,44 +1,53 @@
-name: GitHub Pages
+name: Documentation
 
 on:
   push:
-    branches:
-      - main
+    branches: [main]
   pull_request:
-    branches:
-      - main
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: documentation-${{ github.ref }}
+  cancel-in-progress: true
 
 jobs:
-  deploy:
+  build:
     runs-on: ubuntu-latest
-    concurrency:
-      group: ${{ github.workflow }}-${{ github.ref }}
     steps:
-      - uses: actions/checkout@main
-
-      - name: Setup Node
-        uses: actions/setup-node@main
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
         with:
-          node-version: '20'
-
-      - name: Get yarn cache
-        id: yarn-cache
-        run: echo "::set-output name=dir::$(yarn cache dir)"
-
-      - name: Cache dependencies
-        uses: actions/cache@main
+          node-version-file: .node-version
+      - uses: oven-sh/setup-bun@v2
         with:
-          path: ${{ steps.yarn-cache.outputs.dir }}
-          key: ${{ runner.os }}-website-${{ hashFiles('**/yarn.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-website-
-
-      - run: yarn install --frozen-lockfile
-      - run: yarn build
+          bun-version: 1.3.11
+      - run: bun install --frozen-lockfile
+      - run: bun run build
+      - run: bun run typecheck
+      - run: bun run check:export
+      - uses: actions/upload-artifact@v4
+        with:
+          name: documentation-site
+          path: out
+          include-hidden-files: true
 
-      - name: Deploy
+  deploy:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          name: documentation-site
+          path: out
+      - name: Publish GitHub Pages
         uses: peaceiris/actions-gh-pages@v4
-        if: ${{ github.ref == 'refs/heads/main' }}
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./build
+          publish_dir: out

.gitignore

@@ -1,21 +1,11 @@
-# Dependencies
 /node_modules
-
-# Production
-/build
-
-# Generated files
-.docusaurus
-.cache-loader
-
-# Misc
+/.next
+/out
+/.source
+/docs/apis/v1
+/docs/apis/v2
+*.tsbuildinfo
 .DS_Store
-.env.local
-.env.development.local
-.env.test.local
-.env.production.local
-
-npm-debug.log*
-yarn-debug.log*
-yarn-error.log*
+.env*.local
 .vscode/settings.json
+/public/apis

.node-version

@@ -0,0 +1 @@
+24

AGENTS.md

@@ -0,0 +1,16 @@
+<!-- BEGIN:nextjs-agent-rules -->
+
+## This is NOT the Next.js you know
+
+This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` (resolved from this file's directory; in monorepos the `next` package may not be visible from the repo root) before writing any code. Heed deprecation notices.
+
+This block is written and re-added by `next dev` — verify at `node_modules/next/dist/server/lib/generate-agent-files.js`. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.
+
+<!-- END:nextjs-agent-rules -->
+
+## MCSS documentation exploration
+
+For hands-on MCSS investigation, screenshot capture, and resulting guide updates,
+follow [MCSS_EXPLORATION.md](MCSS_EXPLORATION.md). Read
+[CONTENT_REVIEW.md](CONTENT_REVIEW.md) for existing evidence and unresolved product
+questions before treating inherited instructions as verified behavior.

CONTENT_REVIEW.md

@@ -0,0 +1,152 @@
+# Content review: MCSS 13.10.0
+
+General source review: 15 October 2026. Selected Windows workflows tested:
+16 October 2026; see the [dated evidence report](contributor-notes/mcss-exploration/2026-10-16-windows-13-10-0.md).
+
+## Product authority and scope
+
+The maintainer confirmed in this task that **13.10.0 is current**,
+**mcserversoft.com is authoritative**, and **MCSS is version agnostic**. These are
+explicit product facts, not deductions from the Minecraft or loader projects.
+
+The initial migration rewrote product controls from inherited documentation.
+The 16 October Windows investigation uses a separate, disposable MCSS installation.
+Executable metadata reports `13.10.0.0`, and the actual UI displays `v13.10.0`.
+New captures carry `13-10-0` filenames; inherited captures remain historical
+illustrations. Verification is workflow-specific, not a blanket product approval.
+
+## Windows evidence added on 16 October 2026
+
+Test environment: Windows 11 Pro build 26300, English dark interface, reported
+2560 × 1440 display / 96 DPI, portable Temurin 25.0.4.1. This was not a clean
+Windows/runtime prerequisite test. The evidence report records executable/JAR
+hashes, actual controls, failed cases, and limitations.
+
+- **Create/start/stop:** welcome Create and File → New Server.., Paper selection,
+  JAR picker, creation fields, optional EULA acceptance, the `eula=false` failure,
+  successful Paper 26.3 build 194 readiness, and normal Stop were exercised.
+  MCSS copied the JAR as `paper.jar`. Minecraft client login was not tested.
+- **Java:** a global executable with an empty local override launched the expected
+  runtime. A valid per-server override also launched successfully while the global
+  path deliberately referenced a nonexistent executable. This verifies precedence
+  for the tested Startup Line method, not batch launchers or picker discovery.
+- **Settings/screenshots:** General, Advanced, Crash Handling, server type chooser,
+  first launch, backup filename/retention controls, scheduler forms, and disabled
+  panel/empty credential manager were captured from the actual application.
+  Images with personal paths or the automatically displayed public IP are not
+  published. The backup-settings image is a crop of an actual capture.
+- **Backup:** an empty-blacklist, stopped-server backup reached BACKUP DONE using
+  an existing absolute destination. A relative destination was accepted by the
+  form but failed at execution. The inspected ZIP includes world data, server
+  properties/JAR/libraries/logs, per-server MCSS configuration, and plugin/mod text
+  fixtures. It does not include the application-wide resources configuration.
+  Blacklist matching, retention deletion, live consistency, and Suspend server's
+  automatic stop/start behavior remain untested.
+- **Recovery/import:** extracted into a new directory, checked identical scoreboard
+  file hashes, imported by selecting `server.properties`, started on a separate
+  loopback port, and queried the recovered objective from the console. Import
+  copied the source and created a new server ID/configuration, with no inherited
+  local Java override or backup templates. Other selector files and real
+  loader/modpack imports require their own tests.
+- **Scheduler:** a non-repeating ten-second interval command job ran ten seconds
+  after Paper's readiness message. New `/running/scheduling` documents this tested
+  path, inspected trigger/job controls, and untested timing/condition cases.
+- **Restart:** Restart produced a normal shutdown/save sequence and another
+  successful startup. Elevated restarted the disposable server after its verified
+  Java child was terminated externally, while normal MCSS Stop left it offline.
+  A Minecraft stop command entered through MCSS also left it offline. Aggressive
+  restarted after MCSS Stop. Broader
+  crash causes and server implementations have not been established by this test.
+- **Remote/API:** setup changes applied on leaving Program Settings without an
+  application restart; the management listener was wildcard `::`. Disposable
+  API keys/users were created, authentication and actual response permissions
+  were tested, and all were revoked. Restricted panel sessions returned expected
+  403s in the exercised cases, but restricted API-key results exceeded intended
+  permissions and varied after restart. These discrepancies require maintainer
+  review. Exact sanitized transcripts accompany the report; no guarantee of
+  API-key isolation or complete matrix is asserted. Browser login/CORS and
+  certificate trust deployment were not verified; no browser barrier was bypassed.
+- **Relocation/arguments:** a stopped full installation copied to another folder
+  on the same computer loaded both servers. Paper started using `java @launch.args`
+  and returned the restored objective. Java remained at its existing absolute
+  path outside MCSS. This is not a loader/modpack, new-computer, or upgrade test.
+
+The [official API link](https://www.mcserversoft.com/apidocs) currently redirects to
+the historical API_2.4.1 reference. It is not an installed-build export and does
+not resolve the existing contract gaps. API source specifications remain unchanged.
+
+## External facts updated
+
+- Bounded Vanilla/Fabric runtime ranges through Minecraft 26.3; Java 25 from
+  26.1 and Java 21 from 1.20.5. Paper's differing historical recommendations are
+  separated rather than applied to Vanilla or every loader.
+- NeoForge installation, generated launcher/argument-file use, and complete
+  modpack installation are distinct from single-JAR servers.
+- Waterfall is retired; Geyser is a protocol bridge, not a mod loader or ordinary
+  Java network proxy. Download links now favor original project publishers.
+- Private IPv4 includes 192.168/16. A private WAN address can be local double NAT;
+  it is not proof of ISP CGNAT. Wi-Fi/mobile/satellite are not categorically ruled
+  out. NAT loopback is described as router-dependent rather than an ISP diagnosis.
+- Java TCP and Bedrock/Geyser UDP checks are distinguished. Game access does not
+  require exposing the MCSS management service.
+- JVM encoding changes are distinguished from Windows console/application
+  encoding. DLL/runtime architecture is not inferred from the OS architecture.
+
+The public [Official downloads and resources](docs/reference/versions-and-sources.mdx) page
+and inline links record the primary upstream download and documentation references. All dated
+lab-test notes and caveats are kept in this file and the [dated evidence report](contributor-notes/mcss-exploration/2026-10-16-windows-13-10-0.md)
+rather than inside user-facing guides.
+
+## Assumptions deliberately removed
+
+The rewrite does not promise that a particular Java issue explains every frozen
+MCSS graph, that killing all Java processes is an ordinary fix, that an inaccessible
+JAR proves another process holds it, or that an old registry/performance-counter
+repair is a prerequisite for MCSS 13.10.0. It removes automatic certificate-warning
+bypass advice and false blanket claims about certificates. It does not invent
+MCSS controls for certificate import, backup restoration, scheduled backup
+creation, or arbitrary pack script conversion.
+
+Backup/restore, update planning, and performance investigation are explicit
+operator workflows. They do not claim that an MCSS backup automatically captures
+the application configuration, external databases, or consistent live data.
+
+## API source work and remaining source limitations
+
+The v2 document's introductory description was replaced with readable Markdown,
+and its `apiKey` header is represented by an OpenAPI `type: apiKey`, `in: header`
+security scheme so clients and the playground can supply it. Hardcoded UUIDs in
+`apis/v2.yml` (26 paths) and `apis/v1.yml` (17 paths) were replaced with OpenAPI
+path parameter slugs (`{serverId}`, `{taskId}`, `{backupId}`, `{webhookId}`,
+`{userId}`, `{apiKeyId}`) preserving the original UUIDs as parameter examples,
+and `GET /events` in `apis/v2.yml` was given a sample response and realistic
+header example.
+
+The v2 export is **not** asserted to be a newly generated complete 13.10.0 schema:
+
+- `info.version`, captured response versions/dates, and examples predate this
+  content review. Readers are directed to `GET /api/v2` for live instance data.
+- The v1 security scheme uses a nonstandard HTTP `apikey` scheme. This historical
+  contract has not been reinterpreted as a particular header/token convention.
+- A complete permission matrix, rate limits, pagination rules, and coverage of
+  any additional 13.10.0 endpoints require an authoritative current API export.
+  No such behavior was invented to fill the gaps.
+
+## Follow-up evidence that would improve product-specific detail
+
+The Windows exploration and screenshot workflow is in
+[MCSS_EXPLORATION.md](MCSS_EXPLORATION.md). Its unchecked items remain investigation
+targets, not additional evidence of product behavior. The dated report identifies
+the completed subset.
+
+- A current official prerequisite list for MCSS 13.10.0, including Windows and
+  native runtime requirements, rather than extrapolating old 12.x/13.x notes.
+- Further current captures for real loader/modpack imports and browser panel
+  login, beyond the creation/settings/permission forms captured in this run.
+- An authoritative 13.10.0 API export and investigation of the observed API-key
+  authorization discrepancies before claiming an enforced permission matrix.
+- Backup blacklist, retention deletion, Suspend server, and live-consistency
+  evidence beyond the demonstrated stopped-Paper backup and recovery.
+
+These are source-quality opportunities. They do not block the rewritten general
+Minecraft operation guides or imply a version-compatibility restriction in MCSS.

CONTRIBUTING.md

@@ -1,3 +1,39 @@
-Anyone can add to the documentation. If you want to edit a page, you can do so by clicking "Edit this page" at the bottom of each page. This will take you to GitHub, and from there you will be able to make your changes and create a pull request.
+# Contributing
 
-If you want to add a new page, fork the repository and make your changes in the "docs" folder. Then, create a pull request.
+Edit a guide using its **Edit on GitHub** link, or fork this repository and work
+locally with `bun install --frozen-lockfile` and `bun run dev`.
+
+Write guides as `.mdx` files in `docs/`, with at least a `title` in YAML frontmatter.
+Use each folder's `meta.json` to set its title and page order. Keep existing URLs
+and heading anchors stable when editing published content.
+
+Fumadocs components such as `Callout`, `Tabs`, `Tab`, `Cards`, and `Card` are
+available in MDX. Custom heading anchors use `## Heading [#anchor-name]`.
+Use root-relative links for internal pages and images so they also work on the
+static site, for example `/advanced/java-version` and `/img/docs/example.png`.
+
+Edit API reference in `apis/v1.yml` or `apis/v2.yml`. Do not edit generated files
+under `docs/apis/v1/` or `docs/apis/v2/`; the next build replaces them.
+
+Before opening a pull request, run:
+
+```sh
+bun run build
+bun run typecheck
+bun run check:export
+```
+
+For product questions, visit [MCSS Discord](https://www.mcserversoft.com/discord).
+
+## Content evidence
+
+MCSS is version agnostic; keep Minecraft/Java/loader requirements separate from
+MCSS application behavior. Use mcserversoft.com, maintainer-confirmed facts, and
+existing documented behavior for product claims. Do not infer new controls,
+defaults, or guarantees from how another server manager works.
+
+For changing external facts, use primary project documentation and link the
+source near the claim. Bound version ranges, distinguish minimum requirements
+from recommended runtimes, and date runtime/version reviews. Keep screenshot
+examples distinct from current exact filenames. Update CONTENT_REVIEW.md when
+new product evidence resolves a listed source gap.

Dockerfile

@@ -1,40 +1,12 @@
-## Base ########################################################################
-# Use a larger node image to do the build for native deps (e.g., gcc, python)
-FROM node:lts as base
-
-# Reduce npm log spam and colour during install within Docker
-ENV NPM_CONFIG_LOGLEVEL=warn
-ENV NPM_CONFIG_COLOR=false
-
-# We'll run the app as the `node` user, so put it in their home directory
-WORKDIR /home/node/app
-# Copy the source code over
-COPY --chown=node:node . /home/node/app/
-
-## Development #################################################################
-# Define a development target that installs devDeps and runs in dev mode
-FROM base as development
-WORKDIR /home/node/app
-# Install (not ci) with dependencies, and for Linux vs. Linux Musl (which we use for -alpine)
-RUN npm install
-# Switch to the node user vs. root
-USER node
-# Expose port 3000
-EXPOSE 3000
-# Start the app in debug mode so we can attach the debugger
-CMD ["npm", "start"]
-
-## Production ##################################################################
-# Also define a production target which doesn't use devDeps
-FROM base as production
-WORKDIR /home/node/app
-COPY --from=development /home/node/app/node_modules /home/node/app/node_modules
-# Build the Docusaurus app
-RUN npm run build
-
-## Deploy ######################################################################
-# Use a stable nginx image
-FROM nginx:stable-alpine as deploy
-WORKDIR /home/node/app
-# Copy what we've installed/built from production
-COPY --from=production /home/node/app/build /usr/share/nginx/html/
+FROM oven/bun:1.3.11 AS bun
+FROM node:24-bookworm-slim AS build
+COPY --from=bun /usr/local/bin/bun /usr/local/bin/bun
+WORKDIR /app
+COPY package.json bun.lock source.config.ts ./
+RUN bun install --frozen-lockfile
+COPY . .
+RUN bun run build
+
+FROM nginx:stable-alpine AS deploy
+COPY --from=build /app/out /usr/share/nginx/html
+EXPOSE 80