Merge pull request #2956 from milutinke/ai-dev-workflow-docs

.gitignore

@@ -409,6 +409,8 @@ FodyWeavers.xsd
 
 # docs
 !/docs/.vuepress
+/docs/.vuepress/.cache
+/docs/.vuepress/.temp
 /docs/.vuepress/dist
 
 # translations

docs/.vuepress/client.ts

@@ -0,0 +1,66 @@
+import { computed, defineComponent, h } from 'vue'
+import {
+  defineClientConfig,
+  resolveRouteFullPath,
+  useRoute,
+  useRouter,
+} from 'vuepress/client'
+
+const guardEvent = (event: MouseEvent): boolean => {
+  if (event.metaKey || event.altKey || event.ctrlKey || event.shiftKey) return false
+  if (event.defaultPrevented) return false
+  if (event.button !== undefined && event.button !== 0) return false
+
+  if (event.currentTarget instanceof Element) {
+    const target = event.currentTarget.getAttribute('target')
+    if (target?.match(/\b_blank\b/i)) return false
+  }
+
+  event.preventDefault()
+  return true
+}
+
+const SafeRouteLink = defineComponent({
+  name: 'RouteLink',
+  props: {
+    to: {
+      type: String,
+      required: true,
+    },
+    active: Boolean,
+    activeClass: {
+      type: String,
+      default: 'route-link-active',
+    },
+  },
+  setup(props, { slots }) {
+    const router = useRouter()
+    const route = useRoute()
+    const path = computed(() =>
+      props.to.startsWith('#') || props.to.startsWith('?')
+        ? props.to
+        : `${__VUEPRESS_BASE__}${resolveRouteFullPath(props.to, route.path).substring(1)}`,
+    )
+
+    return () =>
+      h(
+        'a',
+        {
+          class: ['route-link', { [props.activeClass]: props.active }],
+          href: path.value,
+          onClick: (event: MouseEvent) => {
+            if (guardEvent(event)) {
+              void router.push(props.to).catch(() => {})
+            }
+          },
+        },
+        slots.default?.() ?? [],
+      )
+  },
+})
+
+export default defineClientConfig({
+  enhance({ app }) {
+    app.component('RouteLink', SafeRouteLink)
+  },
+})

docs/.vuepress/config.ts

@@ -1,17 +1,17 @@
 import process from 'node:process'
+
 import { viteBundler } from '@vuepress/bundler-vite'
 import { webpackBundler } from '@vuepress/bundler-webpack'
-import { defineUserConfig } from '@vuepress/cli'
+import { markdownChartPlugin } from '@vuepress/plugin-markdown-chart'
+import { redirectPlugin } from '@vuepress/plugin-redirect'
+import { searchPlugin } from '@vuepress/plugin-search'
 import { shikiPlugin } from '@vuepress/plugin-shiki'
 import { defaultTheme } from '@vuepress/theme-default'
-import { getDirname, path } from '@vuepress/utils'
+import { defineUserConfig } from 'vuepress'
-import { searchPlugin } from "@vuepress/plugin-search";
-import { redirectPlugin } from "vuepress-plugin-redirect";
 
 import { headConfig } from './configs/head.js'
 import { mainConfig, defaultThemeConfig } from './configs/locales_config.js'
 
-const __dirname = getDirname(import.meta.url)
 const isProd = process.env.NODE_ENV === 'production'
 
 export default defineUserConfig({
@@ -29,8 +29,9 @@ export default defineUserConfig({
 
   // configure default theme
   theme: defaultTheme({
-    logo: "/images/MCC_logo.png",
+    hostname: 'https://mccteam.github.io',
-    repo: "MCCTeam/Minecraft-Console-Client",
+    logo: '/images/MCC_logo.png',
+    repo: 'MCCTeam/Minecraft-Console-Client',
     docsBranch: 'master',
     docsDir: 'docs',
 
@@ -42,55 +43,58 @@ export default defineUserConfig({
       git: isProd,
       // use shiki plugin in production mode instead
       prismjs: !isProd,
+      seo: isProd
+        ? {
+            canonical: 'https://mccteam.github.io/',
+          }
+        : false,
+      sitemap: isProd
+        ? {
+            changefreq: 'weekly',
+          }
+        : false,
     },
   }),
 
-  // configure markdown
-  markdown: {
-    importCode: {
-      handleImportPath: (str) =>
-        str.replace(/^@vuepress/, path.resolve(__dirname, '../../ecosystem')),
-    },
-  },
-
   // use plugins
   plugins: [
     redirectPlugin({
-      hostname: "https://mccteam.github.io",
+      hostname: 'https://mccteam.github.io',
       config: {
-        "/r/entity.html": "https://github.com/MCCTeam/Minecraft-Console-Client/blob/master/MinecraftClient/Mapping/EntityType.cs",
+        '/r/entity.html': 'https://github.com/MCCTeam/Minecraft-Console-Client/blob/master/MinecraftClient/Mapping/EntityType.cs',
-        "/r/entity/index.html": "https://github.com/MCCTeam/Minecraft-Console-Client/blob/master/MinecraftClient/Mapping/EntityType.cs",
+        '/r/entity/index.html': 'https://github.com/MCCTeam/Minecraft-Console-Client/blob/master/MinecraftClient/Mapping/EntityType.cs',
 
-        "/r/item.html": "https://github.com/MCCTeam/Minecraft-Console-Client/blob/master/MinecraftClient/Inventory/ItemType.cs",
+        '/r/item.html': 'https://github.com/MCCTeam/Minecraft-Console-Client/blob/master/MinecraftClient/Inventory/ItemType.cs',
-        "/r/item/index.html": "https://github.com/MCCTeam/Minecraft-Console-Client/blob/master/MinecraftClient/Inventory/ItemType.cs",
+        '/r/item/index.html': 'https://github.com/MCCTeam/Minecraft-Console-Client/blob/master/MinecraftClient/Inventory/ItemType.cs',
 
-        "/r/block.html": "https://github.com/MCCTeam/Minecraft-Console-Client/blob/master/MinecraftClient/Mapping/Material.cs",
+        '/r/block.html': 'https://github.com/MCCTeam/Minecraft-Console-Client/blob/master/MinecraftClient/Mapping/Material.cs',
-        "/r/block/index.html": "https://github.com/MCCTeam/Minecraft-Console-Client/blob/master/MinecraftClient/Mapping/Material.cs",
+        '/r/block/index.html': 'https://github.com/MCCTeam/Minecraft-Console-Client/blob/master/MinecraftClient/Mapping/Material.cs',
 
-        "/r/l-code.html": "https://github.com/MCCTeam/Minecraft-Console-Client/discussions/2239#discussion-4447461",
+        '/r/l-code.html': 'https://github.com/MCCTeam/Minecraft-Console-Client/discussions/2239#discussion-4447461',
-        "/r/l-code/index.html": "https://github.com/MCCTeam/Minecraft-Console-Client/discussions/2239#discussion-4447461",
+        '/r/l-code/index.html': 'https://github.com/MCCTeam/Minecraft-Console-Client/discussions/2239#discussion-4447461',
 
-        "/r/dc-fmt.html": "https://www.writebots.com/discord-text-formatting/",
+        '/r/dc-fmt.html': 'https://www.writebots.com/discord-text-formatting/',
-        "/r/dc-fmt/index.html": "https://www.writebots.com/discord-text-formatting/",
+        '/r/dc-fmt/index.html': 'https://www.writebots.com/discord-text-formatting/',
 
-        "/r/tg-fmt.html": "https://sendpulse.com/blog/telegram-text-formatting",
+        '/r/tg-fmt.html': 'https://sendpulse.com/blog/telegram-text-formatting',
-        "/r/tg-fmt/index.html": "https://sendpulse.com/blog/telegram-text-formatting",
+        '/r/tg-fmt/index.html': 'https://sendpulse.com/blog/telegram-text-formatting',
       },
     }),
 
-    // only enable shiki plugin in production mode
+    ...(isProd ? [shikiPlugin({ theme: 'dark-plus' })] : []),
-    isProd ? shikiPlugin({ theme: 'dark-plus' }) : [],
 
     searchPlugin({
-        maxSuggestions: 15,
+      maxSuggestions: 15,
-        hotKeys: ["s", "/"],
+      hotKeys: ['s', '/'],
-        locales: {
+      locales: {
-            "/": {
+        '/': {
-                placeholder: "Search",
+          placeholder: 'Search',
-            },
         },
+      },
     }),
 
-    'vuepress-plugin-mermaidjs'
+    markdownChartPlugin({
+      mermaid: true,
+    }),
   ],
 })

docs/.vuepress/configs/l10n_configs/en.ts

@@ -62,6 +62,7 @@ export const defaultThemeConfig_en: DefaultThemeLocaleData = {
         "/guide/creating-text-script.md",
         "/guide/chat-bots.md", 
         "/guide/creating-bots.md", 
+        "/guide/ai-assisted-development.md",
         "/guide/contibuting.md"
     ],
 

docs/README.md

@@ -18,6 +18,6 @@ features:
     - title: Automation
       details: Create bots to do automated tasks
     - title: Supported Versions
-      details: 1.4 - 1.20.4
+      details: 1.4.6 - 1.21.11
 footer: Made by MCC Team with ❤️
 ---

docs/guide/README.md

@@ -4,22 +4,29 @@ title: About & Features
 
 # Introduction
 
--   [About](#about)
+- [Introduction](#introduction)
--   [Quick Intro (YouTube Videos)](#quick-intro)
+  - [About](#about)
--   [Features](#features)
+  - [Features](#features)
--   [Why Minecraft Console Client?](#why-minecraft-console-client)
+  - [Why Minecraft Console Client?](#why-minecraft-console-client)
--   [Getting Help](#getting-help)
+  - [Quick Intro](#quick-intro)
--   [Submitting a bug report or an idea/feature-request](#bugs-ideas-feature-requests)
+    - [The list of the tutorials:](#the-list-of-the-tutorials)
--   [Important notes on some features](#notes-on-some-features)
+  - [Getting Help](#getting-help)
--   [Credits](#credits)
+    - [Before getting help](#before-getting-help)
--   [Disclaimer](#disclaimer)
+  - [Bugs, Ideas, Feature Requests](#bugs-ideas-feature-requests)
--   [License](#license)
+    - [Before submitting](#before-submitting)
+  - [AI-Assisted Development](#ai-assisted-development)
+  - [Notes on some features](#notes-on-some-features)
+    - [Inventory, Terrain and Entity Handling](#inventory-terrain-and-entity-handling)
+    - [Path-Finding and Physics](#path-finding-and-physics)
+  - [Credits](#credits)
+  - [Disclaimer](#disclaimer)
+  - [License](#license)
 
 ## About
 
-**Minecraft Console Client (MCC)** is a lightweight cross-platform open-source **Minecraft** TUI client for **Java edition** that allows you to connect to any Minecraft Java server, send commands and receive text messages in a fast and easy way without having to open the main Minecraft game.
+**Minecraft Console Client (MCC)** is a lightweight, cross-platform, open-source **Minecraft** TUI client for **Java Edition**. It lets you connect to Minecraft Java servers, send commands, and receive text messages without launching the main game.
 
-It also provides various automations that you can enable for administration and other purposes, as well as extensible C# API for creating Bots.
+It also includes built-in automation for administration and utility work, plus an extensible C# API for creating bots and runtime scripts.
 
 It was originally made by [ORelio](https://github.com/ORelio) in 2012 on the [Minecraft Forum](http://www.minecraftforum.net/topic/1314800-/), now it's maintained by him and many other contributors from the community.
 
@@ -50,7 +57,7 @@ It was originally made by [ORelio](https://github.com/ORelio) in 2012 on the [Mi
 -   [Terrain Traversing](usage.md#move)
 -   Entity Handling
 
-_NOTE: Some of mentioned features are disabled by default and you will have to turn them on in the configuration file and some may require additional configuration on your part for your specific usage._
+_Note: Some of these features are disabled by default. You need to enable them in the configuration file, and some also require additional setup._
 
 ## Why Minecraft Console Client?
 
@@ -67,7 +74,7 @@ _NOTE: Some of mentioned features are disabled by default and you will have to t
 
 ## Quick Intro
 
-Don't have time to read through the documentation, we got you, our community has made some simple introduction videos about the **Minecraft Console Client**.
+If you do not want to read through the documentation right away, the community has made a few short introduction videos for **Minecraft Console Client**.
 
 ### The list of the tutorials:
 
@@ -83,7 +90,7 @@ Using Commands, Scripts and other features:
 
 ## Getting Help
 
-MCC has a community that is willing to help, we have a Discussions section in out Git Hub repository.
+MCC has an active community, and the GitHub Discussions section is the best place to ask for help.
 
 Click [here](https://github.com/MCCTeam/Minecraft-Console-Client/discussions) to access it.
 
@@ -94,37 +101,43 @@ Click [here](https://github.com/MCCTeam/Minecraft-Console-Client/discussions) to
 
 ## Bugs, Ideas, Feature Requests
 
-Bug reporting, idea submitting or feature requesting are done in the [Issues](https://github.com/MCCTeam/Minecraft-Console-Client/issues) section of our [Github repository]([here](https://github.com/MCCTeam/Minecraft-Console-Client)).
+Bug reports, ideas, and feature requests all go through the [Issues](https://github.com/MCCTeam/Minecraft-Console-Client/issues) section of our [GitHub repository](https://github.com/MCCTeam/Minecraft-Console-Client).
 
-Navigate to the Issues section, search for a bug, idea or a feature using the search option here in the documentation and in the `Issues` section on Git Hub before making your own.
+Before opening a new issue, search both the documentation and the `Issues` section to avoid duplicates.
 
-If you haven't found anything similar, go ahead and click on the `New issue` button, then choose what you want to do.
+If you do not find anything similar, click `New issue` and choose the appropriate template.
 
-If you're reporting a bug, please be descriptive as much as possible, try to explain how to re-create the bug, attack screenshots and logs, make sure that you have [`debugmessages`](configuration.me#debugmessages) set to `true` before sending a bug report or taking a screenshot.
+If you are reporting a bug, be as specific as possible. Explain how to reproduce it, attach screenshots and logs, and make sure debug logging is enabled before collecting them.
 
 ### Before submitting
 
 -   **Please use the search option here or in the `Issues` section and read the documentation so we avoid duplicate questions/ideas/reports. Thank you!**
 -   **Please be kind, patient and respect others. Thank you!**
 
+## AI-Assisted Development
+
+If you want the repeatable agent workflow used by maintainers, start with [AI-Assisted Development](ai-assisted-development.md).
+
 ## Notes on some features
 
 ### Inventory, Terrain and Entity Handling
 
-Inventory handling is currently not supported in versions: `1.4.6 - 1.9` (*The inventory handling code is in the place, but we're missing Item Palettes, on which we're working.*)
+MCC currently supports Minecraft versions `1.4.6` through `1.21.11`.
 
-Terrain handling is currently not supported in versions: `1.4.6 - 1.6`
+Feature support still depends on protocol version:
 
-Entity handling is currently not supported in versions: `1.4.6 - 1.7`
+- Inventory handling is supported on `1.8+`.
+- Terrain handling is supported on `1.7.2+`.
+- Entity handling is supported on `1.8+`.
 
-There features might not always be implemented in the latest version of the game, since they're often subjected to major changes by Mojang, and we need some time to figure out what has changed and to implement the required changes.
+These features may lag behind brand-new Minecraft releases when Mojang changes the protocol or registries in a major way.
 
 If there was a major game update, and the MCC hasn't been updated to support these features, if you're a programmer, feel free to contribute to the project.
 
 ### Path-Finding and Physics
 
 Currently the path-finding and physics have some limitations, those are:
-- Path finding under slabs is not supported (currently being worked on, partialy complete but not avaliable in the main branch)
+- Path finding under slabs is not supported
 - Swimming is not supported yet
 - Jumping is not supported yet
 - Knockback is not supported yet
@@ -186,7 +199,7 @@ We remind you that **you may get banned** by your server for using this program.
 
 Minecraft Console Client is a totally free of charge, open source project.
 
-The source code is available at [Github Repository](https://github.com/MCCTeam/Minecraft-Console-Client)
+The source code is available at the [GitHub repository](https://github.com/MCCTeam/Minecraft-Console-Client)
 
 Unless specifically stated, source code is from the MCC Team or Contributors, and available under CDDL-1.0.
 

docs/guide/ai-assisted-development.md

@@ -0,0 +1,716 @@
+---
+title: AI-Assisted Development
+---
+
+# AI-Assisted Development
+
+This guide documents the MCC AI-assisted development workflow as a real working loop, not a patch generator running on guesses. The goal is to give the agent an environment it can drive on its own: build MCC, start a local server, send commands, inspect logs, and repeat. Once that loop is in place, iteration is faster and regressions are easier to catch.
+
+If you are looking for the broader contributor entry point first, start with [Contributing](contibuting.md) and then come back here for the agent workflow.
+
+The practical goal is a closed loop:
+
+```mermaid
+flowchart LR
+    edit[Edit] --> build[Build]
+    build --> run[Run]
+    run --> test[Test]
+    test --> inspect[Inspect]
+    inspect --> repeat[Repeat]
+    repeat --> edit
+```
+
+<div class="custom-container warning"><p class="custom-container-title">Warning</p>
+
+If you develop on Windows, use WSL2. This workflow is built around Unix-style shells, `tmux`, `python3`, and shell helper functions. Do not try to run the full AI workflow from plain PowerShell or CMD.
+
+</div>
+
+## Index
+
+-   [What This Workflow Covers](#what-this-workflow-covers)
+-   [Setup](#setup)
+-   [How The Harness Works](#how-the-harness-works)
+-   [Repository Tools](#repository-tools)
+-   [Skills](#skills)
+-   [Standard Development Loop](#standard-development-loop)
+-   [Testing And Validation](#testing-and-validation)
+-   [Version Adaptation Notes](#version-adaptation-notes)
+-   [Example Workflows](#example-workflows)
+
+## What This Workflow Covers
+
+This is the workflow for:
+
+-   local MCC development
+-   local offline server testing
+-   AI-assisted debugging
+-   bot authoring
+-   protocol and version adaptation work
+-   documentation work that should still follow the same disciplined loop
+
+It is built around two layers:
+
+-   repo tools in `tools/`, which do the actual work
+-   AI skills in `.skills/`, which tell the agent when and how to use those tools
+
+## Setup
+
+You only do most of this once.
+
+<details>
+<summary><strong>Windows: install WSL2 first</strong></summary>
+
+Open PowerShell as Administrator and run:
+
+```powershell
+wsl --install
+```
+
+If WSL is already enabled and you specifically want Ubuntu, use:
+
+```powershell
+wsl --install -d Ubuntu
+```
+
+If the install stalls at `0.0%`, use:
+
+```powershell
+wsl --install --web-download -d Ubuntu
+```
+
+Restart if Windows asks for it, then open the Ubuntu shell and finish the Linux user setup there.
+
+From this point on, do MCC development inside WSL. That includes cloning the repo, building, running servers, and using AI agent tooling.
+
+Reference: [Microsoft WSL installation guide](https://learn.microsoft.com/windows/wsl/install)
+
+</details>
+
+<details>
+<summary><strong>Linux and macOS: use Bash or Zsh</strong></summary>
+
+Bash and Zsh both work with MCC's helper scripts.
+
+Check your current shell:
+
+```bash
+echo $SHELL
+```
+
+Notes:
+
+-   Bash is the normal baseline on Linux.
+-   Zsh is the default interactive shell on modern macOS.
+-   The helper script `tools/mcc-env.sh` can be sourced from either `~/.bashrc` or `~/.zshrc`.
+
+</details>
+
+<details>
+<summary><strong>Install Git</strong></summary>
+
+Ubuntu, Debian, and derivatives:
+
+```bash
+sudo apt update
+sudo apt install git
+```
+
+Arch Linux:
+
+```bash
+sudo pacman -S git
+```
+
+macOS with Homebrew:
+
+```bash
+brew install git
+```
+
+Verify:
+
+```bash
+git --version
+```
+
+Reference: [Git downloads](https://git-scm.com/downloads)
+
+</details>
+
+<details>
+<summary><strong>Install .NET SDK 10</strong></summary>
+
+MCC currently builds on `.NET 10`. You need the SDK, not just the runtime.
+
+Supported Ubuntu releases and Ubuntu-based distros with the correct feed enabled:
+
+```bash
+sudo apt-get update && sudo apt-get install -y dotnet-sdk-10.0
+```
+
+Debian 12:
+
+```bash
+wget https://packages.microsoft.com/config/debian/12/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
+sudo dpkg -i packages-microsoft-prod.deb
+rm packages-microsoft-prod.deb
+sudo apt-get update && sudo apt-get install -y dotnet-sdk-10.0
+```
+
+Debian 13:
+
+```bash
+wget https://packages.microsoft.com/config/debian/13/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
+sudo dpkg -i packages-microsoft-prod.deb
+rm packages-microsoft-prod.deb
+sudo apt-get update && sudo apt-get install -y dotnet-sdk-10.0
+```
+
+Arch Linux:
+
+```bash
+sudo pacman -S dotnet-sdk
+```
+
+macOS with Homebrew:
+
+```bash
+brew install --cask dotnet-sdk
+```
+
+Verify:
+
+```bash
+dotnet --version
+```
+
+References:
+
+-   [Install .NET on Ubuntu](https://learn.microsoft.com/dotnet/core/install/linux-ubuntu)
+-   [Install .NET on Debian](https://learn.microsoft.com/dotnet/core/install/linux-debian)
+-   [Homebrew `dotnet-sdk` cask](https://formulae.brew.sh/cask/dotnet-sdk)
+
+</details>
+
+<details>
+<summary><strong>Install Java 21</strong></summary>
+
+The local server harness uses `java` directly, so Java 21 needs to be on your `PATH`.
+
+Ubuntu and Ubuntu-based distros:
+
+```bash
+sudo apt update
+sudo apt install openjdk-21-jdk
+```
+
+Debian:
+
+Package availability varies by Debian release. If `openjdk-21-jdk` is not available in your configured repositories, install a current JDK 21 build from your preferred vendor instead of forcing a stale package name.
+
+Arch Linux:
+
+```bash
+sudo pacman -S jdk21-openjdk
+```
+
+macOS with Homebrew:
+
+```bash
+brew install openjdk@21
+sudo ln -sfn "$(brew --prefix openjdk@21)/libexec/openjdk.jdk" /Library/Java/JavaVirtualMachines/openjdk-21.jdk
+```
+
+Homebrew marks `openjdk@21` as keg-only, which is why the symlink step matters.
+
+Verify:
+
+```bash
+java -version
+```
+
+References:
+
+-   [Ubuntu `openjdk-21-jdk` package](https://packages.ubuntu.com/noble/openjdk-21-jdk)
+-   [Arch `jdk21-openjdk` package](https://archlinux.org/packages/extra/x86_64/jdk21-openjdk/)
+-   [Homebrew `openjdk@21` formula](https://formulae.brew.sh/formula/openjdk@21)
+
+</details>
+
+<details>
+<summary><strong>Install Python 3</strong></summary>
+
+Python 3 is required for the RCON helper and the version-adaptation tools.
+
+Ubuntu, Debian, and derivatives:
+
+```bash
+sudo apt update
+sudo apt install python3
+```
+
+Arch Linux:
+
+```bash
+sudo pacman -S python
+```
+
+macOS with Homebrew:
+
+```bash
+brew install python@3.14
+```
+
+Homebrew currently provides Python 3 through the `python@3.14` formula, and aliases it as `python` and `python3`.
+
+Verify:
+
+```bash
+python3 --version
+```
+
+References:
+
+-   [Ubuntu `python3` package](https://packages.ubuntu.com/noble/python/python3)
+-   [Arch `python` package](https://archlinux.org/packages/core/x86_64/python/)
+-   [Homebrew Python formula](https://formulae.brew.sh/formula/python@3.14)
+
+</details>
+
+<details>
+<summary><strong>Install tmux</strong></summary>
+
+The local Minecraft server runs in a `tmux` session so it can keep running while the agent builds and restarts MCC.
+
+Ubuntu, Debian, and derivatives:
+
+```bash
+sudo apt update
+sudo apt install tmux
+```
+
+Arch Linux:
+
+```bash
+sudo pacman -S tmux
+```
+
+macOS with Homebrew:
+
+```bash
+brew install tmux
+```
+
+Verify:
+
+```bash
+tmux -V
+```
+
+</details>
+
+<details>
+<summary><strong>Clone the repo and initialize submodules</strong></summary>
+
+Clone with submodules in one step:
+
+```bash
+git clone https://github.com/MCCTeam/Minecraft-Console-Client.git --recursive
+```
+
+If you already cloned it without submodules:
+
+```bash
+git submodule update --init --recursive
+```
+
+</details>
+
+<details>
+<summary><strong>Prepare a server version and decompiled source</strong></summary>
+
+From the repo root, use the decompiler helper to download the official server jar and create the decompiled source tree:
+
+```bash
+tools/decompile.sh --version 1.20.6
+```
+
+That creates the paths used by the harness and the version-adaptation workflow:
+
+-   `MinecraftOfficial/downloads/1.20.6/server.jar`
+-   `MinecraftOfficial/1.20.6-decompiled/`
+
+If you are doing protocol work, this step is not optional.
+
+</details>
+
+<details>
+<summary><strong>Load the MCC shell helpers in Bash</strong></summary>
+
+Add this line to `~/.bashrc`:
+
+```bash
+source "$HOME/Minecraft/Minecraft-Console-Client/tools/mcc-env.sh"
+```
+
+Reload the shell:
+
+```bash
+source ~/.bashrc
+```
+
+This gives you the helper functions used by the workflow:
+
+-   `mc-start`
+-   `mc-stop`
+-   `mc-cmd`
+-   `mc-log`
+-   `mc-rcon`
+-   `mcc-build`
+-   `mcc-run`
+-   `mcc-cmd`
+-   `mcc-kill`
+-   `mcc-reload`
+
+</details>
+
+<details>
+<summary><strong>Load the MCC shell helpers in Zsh</strong></summary>
+
+Add this line to `~/.zshrc`:
+
+```bash
+source "$HOME/Minecraft/Minecraft-Console-Client/tools/mcc-env.sh"
+```
+
+Reload the shell:
+
+```bash
+source ~/.zshrc
+```
+
+If your clone lives somewhere else, update the path in the `source` line.
+
+</details>
+
+<details>
+<summary><strong>Verify the environment</strong></summary>
+
+Run these checks:
+
+```bash
+git --version
+dotnet --version
+java -version
+python3 --version
+tmux -V
+```
+
+Then make sure the helper functions are loaded:
+
+```bash
+type mc-start
+type mcc-build
+type mcc-run
+```
+
+</details>
+
+## How The Harness Works
+
+AI agents do not get a rich interactive terminal in the same way a human does. That is why this workflow uses a harness instead of relying on live keyboard input.
+
+The moving parts are:
+
+-   a local Minecraft server running in `tmux`
+-   `mc-rcon` for server-side commands such as `/op`, `/give`, `/summon`, or gamerule setup
+-   MCC started with `MCC_FILE_INPUT=1`
+-   `FileInputBot`, which watches `mcc_input.txt` and turns file lines into MCC commands or server chat
+-   logs from MCC and the local server, which the agent can inspect between runs
+
+The result is simple: the agent can change code, rebuild, start the app, inject commands, and read the result without waiting for a human to sit in the terminal.
+
+## Repository Tools
+
+These are the repo-level tools that make the workflow practical.
+
+| Path | Purpose |
+| --- | --- |
+| `tools/mcc-env.sh` | Loads the shell helper functions used for the normal loop. |
+| `tools/start-server.sh` | Starts a local Minecraft server in a named `tmux` session with a FIFO for stdin. |
+| `tools/mc-rcon.sh` | Sends RCON commands to the local server using `python3`. |
+| `tools/decompile.sh` | Downloads `MinecraftDecompiler.jar` if needed, decompiles the requested Minecraft version, and fetches `server.jar` for server-side work. |
+| `tools/diff_registries.py` | Compares registries between two Minecraft versions to show which palettes need updates. |
+| `tools/gen_item_palette.py` | Generates item palette source from decompiled or reported registry data. |
+| `tools/gen_block_palette.py` | Generates block palette source from authoritative block reports. |
+| `tools/gen_entity_palette.py` | Generates entity palette source from registry reports. |
+| `tools/gen_entity_metadata_palette.py` | Generates entity metadata palette source from serializer registration order. |
+| `tools/gen_command_argument_registry.py` | Helps update modern declare-commands registry order. |
+| `tools/gen_block_shapes.py` | Downloads and compacts collision shape data for physics support. |
+
+There is one more piece worth calling out:
+
+-   `MinecraftClient/ChatBots/FileInputBot.cs` is what makes file-driven command injection possible.
+-   It is loaded when `MCC_FILE_INPUT=1` is set.
+-   `mcc-run` in `tools/mcc-env.sh` already sets that flag for you.
+
+## Skills
+
+The tools above do the work. The skills in `.skills/` tell the AI when to use them and what good output looks like.
+
+| Skill | What it is for | Notes |
+| --- | --- | --- |
+| `mcc-dev-workflow` | The default build, run, debug, and local server loop. | This is the skill to use for most day-to-day MCC debugging. It assumes WSL, `tmux`, Java, and the local harness. |
+| `mcc-integration-testing` | Repeatable end-to-end testing against a local offline server. | This skill bundles its own scripts under `.skills/mcc-integration-testing/scripts/`. Those are skill resources, not top-level repo scripts. |
+| `mcc-version-adaptation` | Protocol and palette updates for new Minecraft versions. | Use this when routing, registries, metadata, palettes, or structured components change. |
+| `mcc-chatbot-authoring` | Authoring or repairing built-in bots and standalone `/script` bots. | This skill bundles references and templates under `.skills/mcc-chatbot-authoring/`. It defaults to standalone `/script` bots unless built-in wiring is requested. |
+| `csharp-best-practices` | C# 12 / .NET 10 coding guidance for this repo. | Use it whenever the change touches MCC runtime code. |
+| `humanizer` | Documentation and prose cleanup. | Use it for docs, guides, release notes, and anything that starts sounding machine-written. |
+| `skill-creator` | Creating or evolving skills themselves. | This is for improving the AI workflow, not for normal MCC feature work. |
+
+The important distinction is this:
+
+-   repo tools are executable scripts and source files
+-   skills are instructions, references, templates, and workflow constraints for the AI
+
+Some skills also carry their own bundled resources:
+
+-   `mcc-integration-testing` bundles scripts and a command matrix reference
+-   `mcc-chatbot-authoring` bundles references and bot templates
+-   `skill-creator` bundles scripts, eval tooling, and reviewer assets
+
+## Standard Development Loop
+
+This is the core loop you should expect an agent to follow.
+
+### 1. Start the local server
+
+```bash
+mc-start 1.20.6
+```
+
+Check the recent server output:
+
+```bash
+mc-log 1.20.6
+```
+
+### 2. Build MCC
+
+```bash
+mcc-build
+```
+
+### 3. Run MCC with file input enabled
+
+```bash
+mcc-run
+```
+
+The raw form looks like this:
+
+```bash
+MCC_FILE_INPUT=1 dotnet run --project MinecraftClient -c Release -- CursorBot - localhost:25565
+```
+
+### 4. Set up server state through RCON
+
+Examples:
+
+```bash
+mc-rcon "op CursorBot"
+mc-rcon "gamerule sendCommandFeedback true"
+mc-rcon "give CursorBot diamond_sword 1"
+mc-rcon "summon minecraft:armor_stand ~ ~ ~"
+```
+
+### 5. Drive MCC through `mcc_input.txt`
+
+Examples:
+
+```bash
+mcc-cmd "inventory player list"
+mcc-cmd "entity"
+mcc-cmd "/gamemode creative"
+```
+
+Behavior:
+
+-   lines starting with `/` are sent as server commands or chat
+-   lines without `/` are treated as MCC internal commands first
+-   if a line is not an MCC internal command, it falls back to normal chat sending
+
+### 6. Inspect the result
+
+Read the MCC output and the server log, decide what changed, and either keep iterating or stop.
+
+### 7. Rebuild and restart fast
+
+```bash
+mcc-reload
+```
+
+That is the usual tight loop for regression work.
+
+## Testing And Validation
+
+There are two main testing styles in this workflow.
+
+### Manual validation
+
+This is enough for smaller changes:
+
+-   join the local server
+-   grant operator privileges with `mc-rcon`
+-   run internal MCC commands through `mcc-cmd`
+-   trigger gameplay or server state changes through `mc-rcon`
+-   inspect logs for parsing errors, disconnects, or wrong output
+
+Typical manual checks:
+
+-   inventory listing and creative item injection
+-   entity tracking after `summon`
+-   terrain and chunk handling after join
+-   chat and command flow
+-   explosion, particle, and sound events
+
+### Scripted full-spectrum testing
+
+The `mcc-integration-testing` skill goes further. It bundles its own scripts under `.skills/mcc-integration-testing/scripts/` and expects the shell helpers from `~/.zshrc`.
+
+Treat those scripts as skill-owned resources. Read the skill before running them directly, and do not assume they behave like top-level repo tools.
+
+That skill is designed for repeatable offline validation of:
+
+-   chat
+-   slash commands
+-   MCC internal commands
+-   inventory handling
+-   entity handling
+-   particles and sounds
+-   TNT and explosion handling
+
+Server settings that matter for AI-driven offline testing:
+
+-   `eula=true`
+-   `online-mode=false`
+-   `enforce-secure-profile=false`
+-   `enable-rcon=true`
+-   `rcon.password=test123`
+
+If those are wrong, the loop gets noisy fast.
+
+## Version Adaptation Notes
+
+Version work needs a stricter process than normal bug fixing.
+
+The important rule is simple:
+
+-   for newer versions, especially `1.21.9+`, use server data reports as the authority for items and blocks
+-   use decompiled source for implementation details, field order, codecs, and serializer logic
+-   do not stop at a palette diff; finish with a build and a live server test
+
+The usual order is:
+
+1. `tools/decompile.sh --version <ver>`
+2. generate server reports from `server.jar`
+3. run `tools/diff_registries.py`
+4. regenerate the palettes that actually changed
+5. update version routing and packet handling
+6. build MCC
+7. test against the real target version
+
+That is exactly the sort of work `mcc-version-adaptation` is meant to guide.
+
+## Example Workflows
+
+These are four common patterns this guide is meant to support.
+
+### Example 1: Debug a runtime regression
+
+Use skills:
+
+-   `mcc-dev-workflow`
+-   `csharp-best-practices`
+
+Typical loop:
+
+```bash
+mc-start 1.20.6
+mcc-build
+mcc-run
+mc-rcon "op CursorBot"
+mcc-cmd "inventory player list"
+mcc-cmd "entity"
+```
+
+Then inspect the MCC output, patch the code, and use:
+
+```bash
+mcc-reload
+```
+
+### Example 2: Build or repair a bot
+
+Use skills:
+
+-   `mcc-chatbot-authoring`
+-   `csharp-best-practices`
+-   `mcc-dev-workflow`
+
+Typical flow:
+
+1. Decide whether this should be a standalone `/script` bot or a built-in bot.
+2. Use the authoring skill's references and templates.
+3. Build MCC.
+4. Start a local server and join it.
+5. Test the bot behavior through live commands, chat, or event-driven actions.
+6. Make sure cleanup paths such as `OnUnload()` are correct.
+
+For standalone script work, the skill defaults to `/script` unless built-in repo wiring is explicitly needed.
+
+### Example 3: Adapt MCC to a new Minecraft version
+
+Use skills:
+
+-   `mcc-version-adaptation`
+-   `mcc-dev-workflow`
+-   `mcc-integration-testing`
+
+Typical flow:
+
+```bash
+tools/decompile.sh --version 1.21.11
+```
+
+Generate server reports:
+
+```bash
+cd /tmp
+java -DbundlerMainClass=net.minecraft.data.Main \
+  -jar "$MCC_SERVERS/1.21.11/server.jar" \
+  --reports --output /tmp/mc_reports
+```
+
+Run the registry diff:
+
+```bash
+python3 tools/diff_registries.py 1.21.10 1.21.11 --registry /tmp/mc_reports/reports/registries.json
+```
+
+Then regenerate the palettes that changed, update routing, build MCC, start a local server for the target version, and run live validation before calling the work done.
+
+### Example 4: Write or update documentation for the workflow itself
+
+Use skills:
+
+-   `humanizer`
+-   `skill-creator`, if you are changing the skills rather than just the docs
+
+Typical flow:
+
+1. Re-read the relevant skill files and repo tools.
+2. Update the guide so the written process matches the real process.
+3. Keep the instructions concrete enough that another contributor can follow them without guessing.
+4. If the workflow itself changed, update the relevant skill too instead of leaving the docs ahead of the automation.

docs/guide/chat-bots.md

@@ -17,7 +17,6 @@ redirectFrom:
 
 <div class="custom-container warning"><p class="custom-container-title">Warning</p>
 
-**Recently we have changed the configuration format from INI to TOML, this part of the documentation has only been partially updated, it's work in progress, for the time being please refer to the `MinecraftClient.ini` for setting names, the descriptions and options should be up to date in most cases, but not guaranteed.**
 
 </div>
 
@@ -29,30 +28,32 @@ redirectFrom:
 
 ## List of built-in Chat Bots
 
--   [Alerts](#alerts)
+- [Chat Bots](#chat-bots)
--   [Anti AFK](#anti-afk)
+  - [About](#about)
--   [Auto Attack](#auto-attack)
+  - [List of built-in Chat Bots](#list-of-built-in-chat-bots)
--   [Auto Craft](#auto-craft)
+  - [Alerts](#alerts)
--   [Auto Dig](#auto-dig)
+  - [Anti AFK](#anti-afk)
--   [Auto Drop](#auto-drop)
+  - [Auto Attack](#auto-attack)
--   [Auto Eat](#auto-eat)
+  - [Auto Craft](#auto-craft)
--   [Auto Fishing](#auto-fishing)
+  - [Auto Dig](#auto-dig)
--   [Auto Relog](#auto-relog)
+  - [Auto Drop](#auto-drop)
--   [Auto Respond](#auto-respond)
+  - [Auto Eat](#auto-eat)
--   [Chat Log](#chat-log)
+  - [Auto Fishing](#auto-fishing)
--   [Discord Bridge](#discord-bridge)
+  - [Auto Relog](#auto-relog)
--   [Farmer](#farmer)
+  - [Auto Respond](#auto-respond)
--   [Follow Player](#follow-player)
+  - [Chat Log](#chat-log)
--   [Hangman](#hangman)
+  - [Discord Bridge](#discord-bridge)
--   [Mailer](#mailer)
+  - [Farmer](#farmer)
--   [Map](#map)
+  - [Follow player](#follow-player)
--   [PlayerList Logger](#playerlist-logger)
+  - [Hangman](#hangman)
--   [Remote Control](#remote-control)
+  - [Mailer](#mailer)
--   [Replay Mod](#replay-mod)
+  - [Map](#map)
--   [Script Scheduler](#script-scheduler)
+  - [PlayerList Logger](#playerlist-logger)
--   [Telegram Bridge](#telegram-bridge)
+  - [Remote Control](#remote-control)
--   [Items Collector](#items-collector)
+  - [Replay Capture](#replay-capture)
--   [WebSocket](#websocket-chat-bot)
+  - [Script Scheduler](#script-scheduler)
+  - [Telegram Bridge](#telegram-bridge)
+  - [Items Collector](#items-collector)
 
 ## Alerts
 
@@ -347,7 +348,7 @@ redirectFrom:
 
         To enable it, set `Custom` (boolean) to `true` and change `value` (double) to your preferred value (eg. `1.5`).
 
-        By the default, this is disabled and the MCC calculates it based on the server TPS.
+        By default, this is disabled and MCC calculates it based on the server TPS.
 
     -   **Format:** `Cooldown_Time = { Custom = <is enabled (true|false)>, value = <seconds (double)> }`
 
@@ -2576,70 +2577,3 @@ redirectFrom:
     -   **Default:** `true`
 
 
-## WebSocket Chat Bot
-
--   **Description:**
-
-    This chat bot allows you to remotely execute commands on the MCC and make Chat Bots in other programming languages over Web Socket.
-
-    You can make your own library to do this, or use the reference implementation one which has been writen in TypeScript/JavaScript: [MCC.js](https://github.com/milutinke/MCC.js)
-
-    If you want to write your own library, you can follow this guide on the protocol specification and avaliable events and commands: [WebSocket Chat Bot Guide](websocket/README.md)
-
--   **Settings:**
-
-    **Section:** **`ChatBot.WebSocketBot`**
-
-    #### `Enabled`
-
-    -   **Description:**
-  
-        This setting specifies if the Web Socket chat bot is enabled.
-
-    -   **Available values:** `true` and `false`.
-
-    -   **Type:** `boolean`
-
-    -   **Default:** `false`
-
-    #### `Ip`
-
-    -   **Description:**
-
-        The IP address that Websocket server will be bound to.
-
-    -   **Type:** `string`
-
-    -   **Default:** `127.0.0.1` (localhost)
-
-    #### `Port`
-
-    -   **Description:**
-
-        The Port that Websocket server will be bound to.
-
-    -   **Type:** `number`
-
-    -   **Default:** `8043`
-
-    #### `Password`
-
-    -   **Description:**
-
-        A password that will be used to authenticate on thw Websocket server 
-        
-        **It is recommended to change the default password and to set a strong one**
-
-    -   **Type:** `string`
-
-    -   **Default:** `wspass12345`
-
-    #### `DebugMode`
-
-    -   **Description:**
-
-        This setting is for developers who are developing a library that uses this chat bot to remotely execute procedures/commands/functions.
-
-    -   **Type:** `boolean`
-
-    -   **Default:** `false`

docs/guide/configuration.md

@@ -7,34 +7,33 @@ redirectFrom:
 
 # Configuration
 
-**Minecraft Console Client** can be both configured by the [command line parameters](usage.md#command-line-parameters) and the configuration file.
+**Minecraft Console Client** can be configured through both [command-line parameters](usage.md#command-line-parameters) and the configuration file.
 
-By the default all of the configurations are stored in the configuration file named `MinecraftClient.ini` which is created the first time you run the program, but you also can specify your own configuration file by providing a path to it as a first parameter when starting the MCC, check out [Usage](usage.md#quick-usage-of-mcc-with-examples) for examples.
+By default, MCC stores its settings in `MinecraftClient.ini`, which is created the first time you run the program. You can also pass a custom configuration file path as the first argument when starting MCC. See [Usage](usage.md#quick-usage-of-mcc-with-examples) for examples.
 
 <div class="custom-container warning"><p class="custom-container-title">Warning</p>
 
-**Recently we have changed the configuration format from INI to TOML, the documentation had to be updated. If you spot a mistake, please report it on our Discord or in the repository as an issue.**
 
 </div>
 
 ## Notes
 
--   Some settings will be omitted from the documentation due to them being not used often, we do not want documentation to be cluttered, we advise you to manually read through the configuration file, where every setting has a description next to it.
+-   Some less common settings are not repeated here. The generated config file contains inline descriptions for every setting.
--   Some plugin/bot related settings will be covered in the plugins section, not here
+-   Bot-specific settings are documented in [Chat Bots](chat-bots.md).
 
 ## Configuration File
 
 ### Format
 
-The configuration file uses the [TOML format](https://toml.io/en/), all of the options are key-value pairs separated into sections.
+The configuration file uses the [TOML format](https://toml.io/en/). Options are key-value pairs grouped into sections.
 
-Sections are defined in-between the square brackets (Example: `[This is a section]`), each occurrence of this marks a beginning of a new section.
+Sections are defined between square brackets, for example `[This is a section]`.
 
-The settings/options are defined as key-value pairs, where the name of the setting and the value are separated by the equals sign `=` (Example: `some-setting=some value`).
+Settings are written as key-value pairs, with the key and value separated by `=`, for example `some-setting = "some value"`.
 
 Lines starting with `#` are comments, they do not have an effect on the configuration of the program, their purpose is purely a descriptive one.
 
-**To get familiar with all the data types and styles of settings please read the [official TOML documenation](https://toml.io/en/v1.0.0).**
+**For the full syntax and data types, see the [official TOML documentation](https://toml.io/en/v1.0.0).**
 
 Full Example:
 
@@ -52,7 +51,7 @@ Section_Enabled = true
 colors = [ "red", "yellow", "green" ]
 
 [ThirdSection.Subsection]
-Coordinate = { x = 145, y = 64, y = 2045 }
+Coordinate = { x = 145, y = 64, z = 2045 }
 ```
 
 ## Main Section
@@ -107,11 +106,11 @@ Coordinate = { x = 145, y = 64, y = 2045 }
 
 -   **Description:**
 
-    This setting is where you define the type of your account: `mojang` or `microsoft`
+    This setting defines the account type: `mojang`, `microsoft`, or `yggdrasil`.
 
     <div class="custom-container tip"><p class="custom-container-title">Tip</p>
 
-    **Mojang accounts are going to stop working soon for everyone, they already are not working for some people.**
+    **Use `microsoft` for normal Microsoft accounts. `yggdrasil` is for custom authlib/Yggdrasil servers.**
 
     </div>
 
@@ -159,12 +158,12 @@ Coordinate = { x = 145, y = 64, y = 2045 }
 
 -   **Type:** `string`
 
--   **Default:** `en_gb`
+-   **Default:** `en_us`
 
 -   **Example:**
 
     ```
-    Language = "en_gb"
+    Language = "en_us"
     ```
 
 #### `ConsoleTitle`
@@ -268,7 +267,7 @@ Coordinate = { x = 145, y = 64, y = 2045 }
 
     <div class="custom-container tip"><p class="custom-container-title">Tip</p>
 
-    **MCC supports only 1.4.6 - 1.19.2**
+    **Current code support is `1.4.6` through `1.21.11`.**
 
     </div>
 
@@ -286,7 +285,7 @@ Coordinate = { x = 145, y = 64, y = 2045 }
     -   `no`
     -   `force`
 
--   **Default:** `auto`
+-   **Default:** `no`
 
     <div class="custom-container tip"><p class="custom-container-title">Tip</p>
 

docs/guide/contibuting.md

@@ -4,9 +4,17 @@ title: Contributing
 
 # Contributing
 
-At this moment this page needs to be created.
+This page is still being filled in. For now, use the sections below as the current contributor entry points for code, docs, and translation work.
 
-For now you can use our article from the [Git Hub repository Wiki](https://github.com/MCCTeam/Minecraft-Console-Client/wiki/Update-console-client-to-new-version) written by [ReinforceZwei](https://github.com/ReinforceZwei).
+If you are doing maintainer-style work with coding agents, start with [AI-Assisted Development](ai-assisted-development.md). It covers the shell setup, local server loop, and the skills in `.skills/`.
+
+You can also use the guide in the [GitHub repository wiki](https://github.com/MCCTeam/Minecraft-Console-Client/wiki/Update-console-client-to-new-version) written by [ReinforceZwei](https://github.com/ReinforceZwei).
+
+For now, the project has three main contribution paths:
+
+-   code and bot work in the main MCC client
+-   documentation updates in `docs/`
+-   translations through Crowdin
 
 ## Translations
 
@@ -14,12 +22,12 @@ To improve translations for MCC, please visit: [Crowdin - Minecraft Console Clie
 
 **It is recommended to translate `MCC in-app text` first.**
 
-If you can't find the language you want to translate into, please contact us at Github or Discord to add it.
+If you cannot find the language you want to translate into, contact us on GitHub or Discord and we can add it.
 
-Github: <a href="https://github.com/MCCTeam/Minecraft-Console-Client" rel="nofollow noopener" target="_blank">https://github.com/MCCTeam/Minecraft-Console-Client</a>
+GitHub: <a href="https://github.com/MCCTeam/Minecraft-Console-Client" rel="nofollow noopener" target="_blank">https://github.com/MCCTeam/Minecraft-Console-Client</a>
 
 Discord: <a href="https://discord.gg/9HPr2EE4C4" rel="nofollow noopener" target="_blank">https://discord.gg/9HPr2EE4C4</a>
 
 ## Contributors
 
-[Check out our contributors on Github](https://github.com/MCCTeam/Minecraft-Console-Client/graphs/contributors).
+[Check out our contributors on GitHub](https://github.com/MCCTeam/Minecraft-Console-Client/graphs/contributors).

docs/guide/creating-bots.md

@@ -8,13 +8,14 @@ title: Creating Chat Bots
 -   [Requirements](#requirements)
 -   [Quick Introduction](#quick-introduction)
 -   [Examples](#examples)
+-   [AI-Assisted Bot Authoring](#ai-assisted-bot-authoring)
 -   [C# API](#c#-api)
 
 ## Notes
 
 <div class="custom-container tip"><p class="custom-container-title">Tip</p>
 
-**For now this page contains only the bare basics of the Chat Bot API, enough of details to teach you how to make basic Chat Bots. For more details you need to take a look at the [ChatBot.cs](https://github.com/MCCTeam/Minecraft-Console-Client/blob/master/MinecraftClient/Scripting/ChatBot.cs) and [Examples](#examples). This page will be improved in the future.**
+**This page covers the basics of the Chat Bot API. For the full surface area, read [ChatBot.cs](https://github.com/MCCTeam/Minecraft-Console-Client/blob/master/MinecraftClient/Scripting/ChatBot.cs) and the example scripts linked below.**
 
 </div>
 
@@ -33,8 +34,8 @@ Crash courses:
 
 More in-depth:
 
--   [Learn C# Youtube Playlist by Microsoft](https://www.youtube.com/playlist?list=PLdo4fOcmZ0oVxKLQCHpiUWun7vlJJvUiN)
+-   [Learn C# YouTube Playlist by Microsoft](https://www.youtube.com/playlist?list=PLdo4fOcmZ0oVxKLQCHpiUWun7vlJJvUiN)
--   [Getting started with C# (An index of tutorials and the documentation) by Microsoft](https://docs.microsoft.com/en-us/dotnet/csharp/)
+-   [Getting started with C# (an index of tutorials and documentation) by Microsoft](https://learn.microsoft.com/en-us/dotnet/csharp/)
 
 ## Quick Introduction
 
@@ -42,7 +43,7 @@ This introduction assumes that you have the basic knowledge of C#.
 
 <div class="custom-container tip"><p class="custom-container-title">Tip</p>
 
-**Here we will use terms Chat Bot and Script interchangeably**
+**In this page, "Chat Bot" and "Script" are used interchangeably.**
 
 </div>
 
@@ -59,8 +60,8 @@ MCC.LoadBot(new ExampleChatBot());
 
 // The code and comments above are defining a "Script Metadata" section
 
-// Every single chat bot (script) must be a class which extends the ChatBot class.
+// Every chat bot script must define a class that extends ChatBot.
-// Your class must be instantiates in the "Script Metadata" section and passed to MCC.LoadBot function.
+// Instantiate that class in the script metadata section and pass it to MCC.LoadBot.
 class ExampleChatBot : ChatBot
 {
     // This method will be called when the script has been initialized for the first time, it's called only once
@@ -92,7 +93,7 @@ class ExampleChatBot : ChatBot
 
 Start MCC, connect to a server and run the following internal command: `/script ExampleChatBot.cs`.
 
-If you did everything right you should see: `[Example Chat Bot] An example Chat Bot has been initialised!` message appear in your console log.
+If everything worked, you should see `[Example Chat Bot] An example Chat Bot has been initialized!` in the console.
 
 ### Structure of Chat Bots
 
@@ -111,9 +112,9 @@ Every single Chat Bot (Script) must have this section at the beginning in order
 
 `//MCCScript 1.0` marks the beginning of the **Script Metadata** section, this must always be on the first line or the Chat Bot (Script) will not load and will throw an error.
 
-`//MCCScript Extensions` marks the end of the **Script Metadata** section, this must be defined before a Chat Bot (Script) class.
+`//MCCScript Extensions` marks the end of the **Script Metadata** section. It must appear before the Chat Bot class.
 
-In order for your Chat Bot (Script) to properly load in-between the `//MCCScript 1.0` and the `//MCCScript Extensions` lines you must instantiate your Chat Bot (Script) class and pass it to the `MCC.LoadBot` function.
+To load a Chat Bot script, instantiate the bot class between `//MCCScript 1.0` and `//MCCScript Extensions`, then pass it to `MCC.LoadBot`.
 
 Example code:
 
@@ -121,7 +122,7 @@ Example code:
 MCC.LoadBot(new YourChatBotClassNameHere());
 ```
 
-**Script Metadata** section allows for including C# packages and libraries with: `//using <namespace>` and `/dll <dll name>`.
+The **Script Metadata** section also lets you include namespaces and DLL references with `//using <namespace>` and `//dll <dll name>`.
 
 <div class="custom-container tip"><p class="custom-container-title">Tip</p>
 
@@ -129,7 +130,7 @@ MCC.LoadBot(new YourChatBotClassNameHere());
 
 </div>
 
-By the default the following packages are loaded:
+By default, the following namespaces are loaded:
 
 ```csharp
 using System;
@@ -167,28 +168,71 @@ MCC.LoadBot(new ExampleChatBot());
 
 ### Chat Bot Class
 
-After the end of the **Script Metadata** section, you basically can define any number of classes you like, the only limitation is that the main class of your Chat Bot (Script) must extend `ChatBot` class.
+After the **Script Metadata** section, you can define any number of helper classes. The main bot class must extend `ChatBot`.
 
 There are no required methods, everything is optional.
 
-When the Chat Bot (Script) has been initialized for the first time the `Initialize` method will be called.
+When the Chat Bot is initialized for the first time, the `Initialize` method is called.
 
-In it you can initialize variables, eg. Dictionaries, etc..
+Use it to initialize state such as dictionaries or cached values.
 
 <div class="custom-container tip"><p class="custom-container-title">Tip</p>
 
 **For allocating resources like a database connection, we recommend allocating them in `AfterGameJoined` and freeing them in `OnDisconnect`**
 
-</div>.
+</div>
 
 ## Examples
 
-You can find a lot of examples in our Git Hub Repository at [ChatBots](https://github.com/MCCTeam/Minecraft-Console-Client/tree/master/MinecraftClient/ChatBots) and [config](https://github.com/MCCTeam/Minecraft-Console-Client/tree/master/MinecraftClient/config).
+You can find more examples in the [ChatBots](https://github.com/MCCTeam/Minecraft-Console-Client/tree/master/MinecraftClient/ChatBots) and [config](https://github.com/MCCTeam/Minecraft-Console-Client/tree/master/MinecraftClient/config) folders in the GitHub repository.
+
+## AI-Assisted Bot Authoring
+
+If you are using an AI coding agent on this repository, use the `mcc-chatbot-authoring` skill for bot work.
+
+Skill links:
+
+-   [Browse the skill on GitHub](https://github.com/MCCTeam/Minecraft-Console-Client/tree/master/.skills/mcc-chatbot-authoring)
+-   [Download the skill directory](https://download-directory.github.io/?url=https%3A%2F%2Fgithub.com%2FMCCTeam%2FMinecraft-Console-Client%2Ftree%2Fmaster%2F.skills%2Fmcc-chatbot-authoring)
+
+This skill is meant for:
+
+-   standalone `/script` bots
+-   built-in MCC chat bots
+-   bot repairs and ports
+-   event handlers, movement logic, inventory logic, and plugin-channel work
+
+Its default behavior is important: if you ask for "a bot" without saying otherwise, it should prefer a standalone `//MCCScript` bot loaded with `/script`. It should only choose a built-in bot when you explicitly ask for repo wiring, automatic config loading, or a compiled MCC bot.
+
+The skill also follows MCC-specific rules, for example:
+
+-   do not send chat from `Initialize()`
+-   use `AfterGameJoined()` for chat or commands after login
+-   normalize chat with `GetVerbatim(text)` before `IsChatMessage(...)` or `IsPrivateMessage(...)`
+-   fully clean up commands, timers, plugin channels, and movement locks
+
+### Example prompts
+
+```text
+Create a standalone MCC /script bot that watches public chat for the word "auction" and logs matching messages to the console. Use the mcc-chatbot-authoring skill.
+```
+
+```text
+Fix this existing MCC script bot so it stops sending chat from Initialize() and moves the startup command to AfterGameJoined(). Use the mcc-chatbot-authoring skill.
+```
+
+```text
+Make a built-in MCC chat bot named AutoTorch and wire it fully into the repo config and bot registration. Use the mcc-chatbot-authoring skill.
+```
+
+```text
+Create a standalone MCC /script bot that follows private messages, uses GetVerbatim(text), and replies only to bot owners. Use the mcc-chatbot-authoring skill.
+```
 
 ## C# API
 
-As of the time of writing, the C# API has been changed in forks that are yet to be merged, so for now you can use the [ChatBot.cs](https://github.com/MCCTeam/Minecraft-Console-Client/blob/master/MinecraftClient/Scripting/ChatBot.cs) for reference.
+The authoritative reference for the C# API is [ChatBot.cs](https://github.com/MCCTeam/Minecraft-Console-Client/blob/master/MinecraftClient/Scripting/ChatBot.cs).
 
 Each method is well documented with standard C# documentation comments.
 
-In the future we will make a script to auto-generate this section based on the documentation in the code.
+This page intentionally stays focused on the basics. For newer hooks and overloads, check the source file directly.

docs/guide/creating-text-script.md

@@ -4,9 +4,9 @@ title: Creating Simple Script
 
 # Creating Simple Script
 
-A simple script is a text file with one command per line. See [Internal Commands](https://mccteam.github.io/guide/usage.html#internal-commands) section or type `/help` in the console to see available commands. Any line beginning with `#` is ignored and treated as a comment.
+A simple script is a text file with one command per line. See the [Internal Commands](usage.md#internal-commands) section, or type `/help` in the console to see the available commands. Any line beginning with `#` is ignored and treated as a comment.
 
-Application variables defined using the set command or [AppVars] INI section can be used. The following read-only variables can also be used: `%username%, %login%, %serverip%, %serverport%, %datetime%`
+Application variables defined with the `set` command or in the `[AppVars]` config section can be used. The following read-only variables are also available: `%username%`, `%login%`, `%serverip%`, `%serverport%`, `%datetime%`.
 
 ## Example
 
@@ -21,6 +21,6 @@ send Now quitting. Bye :)
 exit
 ```
 
-Go to [example scripts](https://github.com/MCCTeam/Minecraft-Console-Client/tree/master/MinecraftClient/config) to see more example.
+See the [example scripts](https://github.com/MCCTeam/Minecraft-Console-Client/tree/master/MinecraftClient/config) folder for more examples.
 
-If you want need advanced functions, please see [Creating Chat Bots](creating-bots.md)
+If you need more advanced behavior, see [Creating Chat Bots](creating-bots.md).

docs/guide/installation.md

@@ -20,7 +20,7 @@ If you're not the kind of person that likes textual tutorials, our community has
 
 ## Download a compiled binary
 
-You can download a compiled binary file of the latest build from our Releases section on Git Hub: [Download](https://github.com/MCCTeam/Minecraft-Console-Client/releases)
+You can download a compiled binary of the latest build from the [GitHub Releases](https://github.com/MCCTeam/Minecraft-Console-Client/releases) page.
 
 ## Building from the source code
 
@@ -33,7 +33,7 @@ However, if you want to build the program from source code, please follow the gu
 Requirements:
 
 -   [Git](https://www.git-scm.com/)
--   [.NET 7.0 or new-er](https://dotnet.microsoft.com/en-us/download) or [Visual Studio](https://visualstudio.microsoft.com/) configured for C# app development
+-   [.NET 10 SDK](https://dotnet.microsoft.com/en-us/download) or [Visual Studio](https://visualstudio.microsoft.com/) configured for C# app development
 
 <div class="custom-container tip"><p class="custom-container-title">Tip</p>
 
@@ -48,12 +48,18 @@ Install [Git](https://www.git-scm.com/)
 1. Make a new folder where you want to keep the source code
 2. Then open it up, hold `SHIFT` and do a `right-click` on the empty white space in the folder
 3. Click on `Git Bash Here` in the context menu
-4. Clone the [Git Hub Repository](https://github.com/MCCTeam/Minecraft-Console-Client) by typing end executing the following command:
+4. Clone the [GitHub repository](https://github.com/MCCTeam/Minecraft-Console-Client) by running:
 
 ```bash
 git clone https://github.com/MCCTeam/Minecraft-Console-Client.git --recursive
 ```
 
+If you cloned the repository without `--recursive`, run:
+
+```bash
+git submodule update --init --recursive
+```
+
 5. Once the repository has been cloned, you can close the `Git Bash` terminal emulator
 6. Open up the new cloned folder
 
@@ -83,19 +89,37 @@ git clone https://github.com/MCCTeam/Minecraft-Console-Client.git --recursive
 6. Right click on `MinecraftClient` solution in the `Solution Explorer`
 7. Click `Build`
 
-If the build has succeeded, the compiled binary `MinecraftClient.exe` will be in `MinecraftClient/bin/Release/net7.0/win-x64/publish` folder.
+If the build succeeds, the published binary `MinecraftClient.exe` will be in `MinecraftClient/bin/Release/net10.0/win-x64/publish/`.
 
 #### Building using .NET manually without Visual Studio
 
 1. Open the `Minecraft-Console-Client` folder you've cloned or downloaded
 2. Open the PowerShell (`Right-Click` on the whitespace and click `Open PowerShell`, or in Windows Explorer: `File -> Open PowerShell`)
-3. Run the following command to build the project:
+3. Install the .NET 10 SDK if you do not already have it. The easiest current option on Windows is:
 
-```bash
+```powershell
-dotnet publish MinecraftClient -f net7.0 -r win-x64 --no-self-contained -c Release -p:UseAppHost=true -p:IncludeNativeLibrariesForSelfExtract=true -p:DebugType=None
+winget install Microsoft.DotNet.SDK.10
 ```
 
-If the build has succeeded, the compiled binary `MinecraftClient.exe` will be in `MinecraftClient/bin/Release/net7.0/win-x64/publish` folder.
+4. Run the following command for a normal local build:
+
+```bash
+dotnet build MinecraftClient.sln -c Release
+```
+
+5. If you want a release-like published binary that matches the repo's CI workflow, run:
+
+```bash
+dotnet publish MinecraftClient.sln -f net10.0 -r win-x64 --self-contained=true -c Release -p:UseAppHost=true -p:IncludeNativeLibrariesForSelfExtract=true -p:EnableCompressionInSingleFile=true -p:DebugType=Embedded
+```
+
+6. Verify the SDK installation if needed:
+
+```bash
+dotnet --info
+```
+
+If the publish step succeeds, the published binary `MinecraftClient.exe` will be in `MinecraftClient/bin/Release/net10.0/win-x64/publish/`.
 
 ### Linux, macOS
 
@@ -113,52 +137,76 @@ Requirements:
 
     -   [Install Git on macOS](https://git-scm.com/download/mac)
 
--   .NET SDK 7.0 or new-er
+-   .NET 10 SDK
 
-    -   [Install .NET on Linux](https://docs.microsoft.com/en-us/dotnet/core/install/linux)
+    -   [Install .NET on Linux](https://learn.microsoft.com/en-us/dotnet/core/install/linux)
-    -   [Install .NET on macOS](https://docs.microsoft.com/en-us/dotnet/core/install/macos)
+    -   [Install .NET on Ubuntu](https://learn.microsoft.com/en-us/dotnet/core/install/linux-ubuntu-install)
+    -   [Install .NET on macOS](https://learn.microsoft.com/en-us/dotnet/core/install/macos)
 
 #### Cloning using Git
 
 1. Open up a terminal emulator and navigate to the folder where you will store the MCC
-2. Recursively clone the [Git Hub Repository](https://github.com/MCCTeam/Minecraft-Console-Client) by typing end executing the following command:
+2. Recursively clone the [GitHub repository](https://github.com/MCCTeam/Minecraft-Console-Client) by running:
 
 ```bash
 git clone https://github.com/MCCTeam/Minecraft-Console-Client.git --recursive
 ```
 
 3. Go to the folder you've cloned (should be `Minecraft-Console-Client`)
-4. If you want to download translation resources, please check out [Download translation resources](#download-translation-resources-optional)
+4. Install the .NET 10 SDK.
-5. Run the following command to build the project:
+
+    - On Ubuntu 24.04 LTS, use the built-in Ubuntu package feeds:
+
+        ```bash
+        sudo apt-get update && \
+          sudo apt-get install -y dotnet-sdk-10.0
+        ```
+
+    - On macOS, the normal path is to use the official installer from the [.NET download page](https://dotnet.microsoft.com/en-us/download). Pick `Arm64` for Apple Silicon and `x64` for Intel Macs.
+
+5. If you want to download translation resources, please check out [Download translation resources](#download-translation-resources-optional)
+6. Run the following command for a normal local build:
+
+    ```bash
+    dotnet build MinecraftClient.sln -c Release
+    ```
+
+7. Run the following command if you want a release-like published binary that matches the repo's CI workflow:
 
     - On Linux:
 
         ```bash
-        dotnet publish MinecraftClient -f net7.0 -r linux-x64 --no-self-contained -c Release -p:UseAppHost=true -p:IncludeNativeLibrariesForSelfExtract=true -p:DebugType=None
+        dotnet publish MinecraftClient.sln -f net10.0 -r linux-x64 --self-contained=true -c Release -p:UseAppHost=true -p:IncludeNativeLibrariesForSelfExtract=true -p:EnableCompressionInSingleFile=true -p:DebugType=Embedded
         ```
 
         <div class="custom-container tip"><p class="custom-container-title">Tip</p>
 
-        **If you're using Linux that is either ARM, 32-bit, Rhel based, Using Musl, or Tirzen, [find an appropriate RID](https://docs.microsoft.com/en-us/dotnet/core/rid-catalog#linux-rids) for your platform and replace the `-r linux-64` with an appropriate `-r RID_NAME` (Example for arm: `-r linux-arm64`)**
+        **If you are using Linux on ARM, 32-bit, RHEL-based distributions, or Musl, [pick the appropriate RID](https://learn.microsoft.com/en-us/dotnet/core/rid-catalog#linux-rids) for your platform and replace `-r linux-x64` with it, for example `-r linux-arm64`.**
 
         </div>
 
     - On macOS:
 
         ```bash
-        dotnet publish MinecraftClient -f net7.0 -r osx-x64 --no-self-contained -c Release -p:UseAppHost=true -p:IncludeNativeLibrariesForSelfExtract=true -p:DebugType=None
+        dotnet publish MinecraftClient.sln -f net10.0 -r osx-x64 --self-contained=true -c Release -p:UseAppHost=true -p:IncludeNativeLibrariesForSelfExtract=true -p:EnableCompressionInSingleFile=true -p:DebugType=Embedded
         ```
 
         <div class="custom-container tip"><p class="custom-container-title">Tip</p>
 
-        **If you're not using MAC with Intel, find an appropriate RID for your ARM processor, [find an appropriate RID](https://docs.microsoft.com/en-us/dotnet/core/rid-catalog#macos-rids) and replace the `-r osx-64` with an appropriate `-r RID_NAME` (Example for arm: `-r osx.12-arm64`)**
+        **If you are not using an Intel Mac, [pick the appropriate RID](https://learn.microsoft.com/en-us/dotnet/core/rid-catalog#macos-rids) for your processor and replace `-r osx-x64` with it, for example `-r osx-arm64`.**
 
         </div>
 
 If the build has succeeded, the compiled binary `MinecraftClient` will be in:
 
--   Linux: `MinecraftClient/bin/Release/net7.0/linux-x64/publish/`
+-   Linux: `MinecraftClient/bin/Release/net10.0/linux-x64/publish/`
--   macOS: `MinecraftClient/bin/Release/net7.0/osx-x64/publish/`
+-   macOS: `MinecraftClient/bin/Release/net10.0/osx-x64/publish/`
+
+You can verify the SDK installation with:
+
+```bash
+dotnet --info
+```
 
 ## Using Docker
 
@@ -175,11 +223,11 @@ Requirements:
 
 <div class="custom-container warning"><p class="custom-container-title">Warning</p>
 
-**Pay attention at warnings, Docker currently works, but you must start the containers in the interactive mode or MCC will crash, we're working on solving this.**
+**Docker works, but you need to start the container in interactive mode. Starting it in headless mode can still crash MCC.**
 
 </div>
 
-1. Clone the [Git Hub Repository](https://github.com/MCCTeam/Minecraft-Console-Client) by typing end executing the following command:
+1. Clone the [GitHub repository](https://github.com/MCCTeam/Minecraft-Console-Client) by running:
 
 ```bash
 git clone https://github.com/MCCTeam/Minecraft-Console-Client.git --recursive
@@ -196,12 +244,12 @@ docker build -t minecraft-console-client:latest .
 
 <div class="custom-container danger"><p class="custom-container-title">Danger</p>
 
-**There is a bug with the ConsoleInteractive which causes a crash when a container is started in a headless mode, so you need to use the interactive mode. Do not restart containers in a classic way, stop then and start them with interactive mode (this command), after that simply detach with `CTRL + P` and then `CTRL + Q`.**
+**Because of a ConsoleInteractive issue, starting the container in headless mode can crash MCC. Start it with the interactive command below, then detach with `CTRL + P` followed by `CTRL + Q` if you want to leave it running in the background.**
 
 </div>
 
 ```bash
-# You could also ignore the -v parameter if you dont want to mount the volume that is up to you. If you don't it's harder to edit the .ini file if thats something you want to do
+# You can omit -v if you do not want a mounted volume. Keeping the volume makes it much easier to edit the TOML config stored in MinecraftClient.ini from the host.
 docker run -it -v <PATH_ON_YOUR_MACHINE_TO_MOUNT>:/opt/data minecraft-console-client:latest
 ```
 
@@ -234,11 +282,11 @@ Remember to remove the container after usage:
 docker-compose down
 ```
 
-If you use the INI file and entered your data (username, password, server) there, you can start your container using
+If you use `MinecraftClient.ini` and entered your data there, you can start your container using
 
 ```bash
 docker-compose up
-docker-compose up -d #for deamonized running in the background
+docker-compose up -d # for daemonized background running
 ```
 
 Note that you won't be able to interact with the client using `docker-compose up`. If you want that functionality, please use the first method: `docker-compose run MCC`.
@@ -251,11 +299,11 @@ docker-compose down
 
 ## Run on Android
 
-It is possible to run the Minecraft Console Client on Android through Termux and Ubuntu 22.04 in it, however it requires a manual setup with a lot of commands, be careful no to skip any steps. Note that this might take anywhere from 10 to 20 minutes or more to do depending on your technical knowledge level, Internet speed and CPU speed.
+It is possible to run Minecraft Console Client on Android through Termux and Ubuntu 24.04, but it requires a manual setup with a lot of commands, so be careful not to skip any steps. Depending on your technical background, internet speed, and device speed, this can take anywhere from 10 to 20 minutes or more.
 
 <div class="custom-container tip"><p class="custom-container-title">Tip</p>
 
-**This section is going to get a bit technical, I'll try my best to make everything as simple as possible. If you are having trouble following along or if you encounter any issues, feel free to open up a discussion on our Github repository page.**
+**This section gets a bit technical. If you run into issues, open a discussion on our GitHub repository page.**
 
 </div>
 
@@ -277,11 +325,11 @@ It is possible to run the Minecraft Console Client on Android through Termux and
 
 <div class="custom-container warning"><p class="custom-container-title">Warning</p>
 
-**The Play Store version of Termux is outdated and not supported, do not use it, use the the [Github one](https://github.com/termux/termux-app/releases/latest/).**
+**The Play Store version of Termux is outdated and not supported. Use the [GitHub release](https://github.com/termux/termux-app/releases/latest/) instead.**
 
 </div>
 
-Go to [the Termux Github latest release](https://github.com/termux/termux-app/releases/latest/), download the `debug_universal.apk`, unzip it and run it.
+Go to [the latest Termux GitHub release](https://github.com/termux/termux-app/releases/latest/), download the `debug_universal.apk`, unzip it, and run it.
 
 <div class="custom-container tip"><p class="custom-container-title">Tip</p>
 
@@ -295,20 +343,20 @@ Go to [the Termux Github latest release](https://github.com/termux/termux-app/re
 
 </div>
 
-#### Installing Ubuntu 22.04
+#### Installing Ubuntu 24.04
 
 At this stage, you have 2 options:
 
 1. Following this textual tutorial
-2. Watching a [Youtube tutorial for installing Ubuntu](https://www.youtube.com/watch?v=5yit2t7smpM)
+2. Watching a [YouTube tutorial for installing Ubuntu](https://www.youtube.com/watch?v=5yit2t7smpM)
 
 <div class="custom-container tip"><p class="custom-container-title">Tip</p>
 
-**If you decide to watch the Youtube tutorial, watch only up to `1:58`, the steps after are not needed and might just confuse you.**
+**If you decide to watch the YouTube tutorial, watch only up to `1:58`. The steps after that are not needed here and might just confuse you.**
 
 </div>
 
-In order to install Ubuntu 22.04 in Termux you require `wget` and `proot`, we're going to install them in the next step.
+In order to install Ubuntu 24.04 in Termux you require `wget` and `proot`, and we are going to install them in the next step.
 
 Once you have Termux installed open it up and run the following command one after other (in order):
 
@@ -350,7 +398,7 @@ Once the installation is complete, you can start Ubuntu with:
 
 #### Installing .NET on ARM
 
-Since there are issues installing .NET 7.0 via the APT package manager at the time of writing, we will have to install it manually.
+If the package-manager route does not provide a current enough SDK for your setup, install .NET manually instead.
 
 First we need to update the APT package manager repositories and install dependencies.
 
@@ -366,7 +414,7 @@ After you did it, we need to install dependencies for .NET, with the following c
 apt install wget nano unzip libc6 libgcc1 libgssapi-krb5-2 libstdc++6 zlib1g libicu70 libssl3 -y
 ```
 
-After you have installed dependencies, it's time to install .NET, you either can follow this tutorial or the [Microsoft one](https://docs.microsoft.com/en-us/dotnet/core/install/linux-scripted-manual#manual-install).
+After you have installed the dependencies, install .NET either by following this guide or by using Microsoft's [manual install instructions](https://learn.microsoft.com/en-us/dotnet/core/install/linux-scripted-manual#manual-install).
 
 Navigate to your `/root` home directory with the following command:
 
@@ -374,31 +422,31 @@ Navigate to your `/root` home directory with the following command:
 cd /root
 ```
 
-First you need to download .NET 7.0, you can do it with the following command:
+Download a current .NET SDK tarball for your platform from Microsoft. Replace the placeholder below with the actual current download URL from the [.NET download page](https://dotnet.microsoft.com/en-us/download):
 
 ```bash
-wget https://download.visualstudio.microsoft.com/download/pr/6cd2eaa7-4c06-4168-b90b-ee2d6bb40b10/4a8387eb07e17d262bfb9965f6d34462/dotnet-sdk-7.0.203-linux-arm64.tar.gz
+wget <current-dotnet-sdk-linux-arm64-tarball-url>
 ```
 
 <div class="custom-container tip"><p class="custom-container-title">Tip</p>
 
-**This tutorial assumes that you have 64 bit version of ARM processor, if you happen to have a 32-bit version replace the link in the command above with [this one](https://download.visualstudio.microsoft.com/download/pr/55972ef4-146e-47e6-b014-0163cbaca6a3/fa9713f73f44088898843016d68c5929/dotnet-sdk-7.0.203-linux-arm.tar.gz)**
+**This example assumes a 64-bit ARM processor. If you are using a different architecture, download the matching SDK archive for that platform instead.**
 
 </div>
 
 <div class="custom-container tip"><p class="custom-container-title">Tip</p>
 
-**This tutorial assumes that you're following along and using Ubuntu 22.04, if you're using a different distro, like Alpine, go to [here](https://dotnet.microsoft.com/en-us/download/dotnet/7.0) and copy an appropriate link for your distro.**
+**This tutorial assumes Ubuntu 24.04. If you are using a different distro, get the current SDK archive for your platform from the [.NET download page](https://dotnet.microsoft.com/en-us/download).**
 
 </div>
 
 Once the file has been downloaded, you need to run the following commands in order:
 
-1. `DOTNET_FILE=dotnet-sdk-7.0.203-linux-arm64.tar.gz`
+1. `DOTNET_FILE=<downloaded-dotnet-sdk-archive-name>`
 
     <div class="custom-container warning"><p class="custom-container-title">Warning</p>
 
-    **If you're using a different download link, update the file name in this command to match your version.**
+    **Replace the placeholder with the exact filename you downloaded. If you are using a different archive, update this value to match it exactly.**
 
     </div>
 
@@ -417,7 +465,7 @@ Now we need to tell our shell to know where the `dotnet` command is, for future
 
 <div class="custom-container warning"><p class="custom-container-title">Warning</p>
 
-**You will need a basic knowledge of Nano text editor, if you do not know how to use it, watch this [Youtube video tutorial](https://www.youtube.com/watch?v=DLeATFgGM-A)**
+**You will need a basic knowledge of the Nano text editor. If you do not know how to use it, watch this [YouTube tutorial](https://www.youtube.com/watch?v=DLeATFgGM-A).**
 
 </div>
 
@@ -537,7 +585,7 @@ Also, here are some linux tutorials for people who are new to it:
 
 <div class="custom-container tip"><p class="custom-container-title">Tip</p>
 
-**This is a new section, if you find a mistake, please report it by opening an Issue in our [Github repository](https://github.com/MCCTeam/Minecraft-Console-Client). Thank you!**
+**This is a newer section. If you spot a mistake, please report it by opening an issue in our [GitHub repository](https://github.com/MCCTeam/Minecraft-Console-Client).**
 
 </div>
 
@@ -558,13 +606,13 @@ VPS stands for a **V**irtual **P**rivate **S**erver, it's basically a remote vir
 
 You can use a VPS for hosting a website, or a an app, or a game server, or your own VPN, or the Minecraft Console Client.
 
-Here is a [Youtube video](https://youtu.be/42fwh_1KP_o) that explains it in more detail if you're interested.
+Here is a [YouTube video](https://youtu.be/42fwh_1KP_o) that explains it in more detail if you are interested.
 
 ### Prerequisites
 
-1. Gitbash (if you're on Windows)
+1. Git Bash (if you are on Windows)
 
-    Download and install [Gitbash](https://git-scm.com/downloads).
+    Download and install [Git Bash](https://git-scm.com/downloads).
 
     <div class="custom-container tip"><p class="custom-container-title">Tip</p>
 
@@ -572,7 +620,7 @@ Here is a [Youtube video](https://youtu.be/42fwh_1KP_o) that explains it in more
 
     </div>
 
-2. `ssh` and `ssh-keygen` commands (On Windows they're available with Gitbash, on macOs and Linux they should be available by default, it not, search on how to install them)
+2. `ssh` and `ssh-keygen` commands (on Windows they are available with Git Bash; on macOS and Linux they should be available by default. If not, install them first.)
 
 3. Basic knowledge of Linux shell commands, terminal emulator usage, SSH and Nano editor.
 
@@ -607,7 +655,7 @@ The MCC is not expensive to run, so it can run on basically any hardware, you do
 
 <div class="custom-container danger"><p class="custom-container-title">Danger</p>
 
-**In this tutorial we will be using `Ubuntu 22.04`, make sure to select it as the OS when buying a VPS.**
+**In this tutorial we will be using `Ubuntu 24.04 LTS`, so pick that family when choosing your VPS image.**
 
 </div>
 
@@ -619,7 +667,7 @@ Some of the reliable and cheap hosting providers (sorted for price/performance):
 
     <div class="custom-container tip"><p class="custom-container-title">Tip</p>
 
-    **Does not have Ubuntu 22.04 in the dropdown menu when ordering, you will have to re-install later or ask support to do it.**
+    **If Ubuntu 24.04 LTS is not in the dropdown when ordering, you may need to reinstall later or ask support to do it.**
 
     </div>
 
@@ -695,7 +743,7 @@ Fill out the `Name` field with a name of your preference.
 
 ![VPS Name](/images/guide/VPS_Name.png)
 
-For the **Application and OS images** select `Ubuntu Server 22.04 LTS (HVM), SSD Volume Type`.
+For the **Application and OS images** select the current `Ubuntu Server 24.04 LTS` image. The exact AWS label may vary slightly by point release.
 
 <div class="custom-container danger"><p class="custom-container-title">Danger</p>
 
@@ -781,7 +829,7 @@ When you order the VPS, most likely you will be asked to provide the root accoun
 
 Other option is that you will get your login info in the email once the setup is done.
 
-Once you have the root login account info, you need [Gitbash](https://git-scm.com/downloads) on Windows and `ssh` if you're on macOS or Linux (if you do not have it by some chance, search on how to install it, it is simple).
+Once you have the root login account info, you need [Git Bash](https://git-scm.com/downloads) on Windows and `ssh` on macOS or Linux.
 
 If you're on Windows open `Git Bash`, on mac OS and Linux open a `Terminal` and type the following command:
 
@@ -1003,9 +1051,9 @@ If did everything correctly you should see a Linux prompt and a welcome message
 
 You can do `whoami` to see your username.
 
-Now you can install .NET Core 7 and MCC.
+Now you can install the .NET 10 SDK and MCC.
 
-### Installing .NET Core 7
+### Installing .NET 10 SDK
 
 <div class="custom-container tip"><p class="custom-container-title">Tip</p>
 
@@ -1013,12 +1061,6 @@ Now you can install .NET Core 7 and MCC.
 
 </div>
 
-<div class="custom-container warning"><p class="custom-container-title">Warning</p>
-
-**With newer versions of .NET Core 7 on Ubuntu 22.04 you might get the following error: `A fatal error occurred, the folder [/usr/share/dotnet/host/fxr] does not contain any version-numbered child folders`, if you get it, use [this solution](https://github.com/dotnet/sdk/issues/27082#issuecomment-1211143446)**
-
-</div>
-
 Log in as the user you've created.
 
 Update the system packages and package manager repositories:
@@ -1027,40 +1069,16 @@ Update the system packages and package manager repositories:
 sudo apt update -y && sudo apt upgrade -y
 ```
 
-Install `wget`:
+On Ubuntu 24.04 LTS, the official Microsoft docs say .NET is available directly from the Ubuntu package feeds, so you do not need to add the old Microsoft package repository for .NET 10. Install the SDK with:
 
 ```bash
-sudo apt install wget -y
+sudo apt-get update -y && sudo apt-get install -y dotnet-sdk-10.0
 ```
 
-Go to your home directory with:
+You can verify the installation with:
 
 ```bash
-cd ~
+dotnet --info
-```
-
-Download the Microsoft repository file:
-
-```bash
-wget https://packages.microsoft.com/config/ubuntu/22.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
-```
-
-Add Microsoft repositories to the package manager:
-
-```bash
-sudo dpkg -i packages-microsoft-prod.deb
-```
-
-Remove the file, we do not need it anymore:
-
-```bash
-rm packages-microsoft-prod.deb
-```
-
-Finally, install .NET Core 7:
-
-```bash
-sudo apt-get update -y && sudo apt-get install -y dotnet-sdk-7.0
 ```
 
 Run the following command to check if everything was installed correctly:
@@ -1085,13 +1103,13 @@ path-to-application:
   The path to an application .dll file to execute.
 ```
 
-If you do not get this output and the installation was not successful, [try other methods](https://docs.microsoft.com/en-us/dotnet/core/install/linux-ubuntu#2204).
+If you do not get this output and the installation was not successful, [try other methods](https://learn.microsoft.com/en-us/dotnet/core/install/linux-ubuntu-install).
 
-If it was successful, you can now install the MCC.
+If it was successful, you can now install MCC.
 
 ### Installing MCC on a VPS
 
-Now that you have .NET Core 7.0 and a user account, you should install the `screen` utility, you will need this in order to keep the MCC running once you close down the SSH session (if you do not have it, the MCC will just stop working once you disconnect). You can look at the `screen` like a window, except it's in a terminal, it lets you have multiple "windows" open at the same time.
+Now that you have the .NET SDK and a user account, install the `screen` utility. You will need it if you want MCC to keep running after you close the SSH session.
 
 <div class="custom-container tip"><p class="custom-container-title">Tip</p>
 
@@ -1099,7 +1117,7 @@ Now that you have .NET Core 7.0 and a user account, you should install the `scre
 
 </div>
 
-You also can learn about the screen command from [this Youtube tutorial](https://youtu.be/_ZJiEX4rmN4).
+You can also learn about the `screen` command from [this YouTube tutorial](https://youtu.be/_ZJiEX4rmN4).
 
 To install the `screen` execute the following command:
 

docs/guide/usage.md

@@ -47,7 +47,7 @@ screen -S mcc
 
 # Detach from the screen by pressing CTRL + A + D
 
-# Re-attach if you want to have accces again
+# Re-attach if you want access again
 screen -r mcc
 ```
 
@@ -59,7 +59,7 @@ See [Run using Docker](./installation.md#using-docker)
 
 ## Command-line usage
 
-**Minecraft Console Client** has a plethora of useful command line parameters, here you can learn about them.
+**Minecraft Console Client** has a number of useful command-line parameters. This section covers the most important ones.
 
 ### For people not familiar with the command line
 
@@ -97,6 +97,8 @@ Here is an example for using a `--help` command line parameter for MCC that will
 MinecraftClient.exe --help
 ```
 
+MCC also supports a few maintenance and debugging switches such as `--upgrade`, `--force-upgrade`, `--generate`, `--keyboard-debug`, `BasicIO`, and `BasicIO-NoColor`.
+
 ### Quick usage of MCC with examples
 
 <div class="custom-container tip"><p class="custom-container-title">Tip</p>
@@ -119,16 +121,16 @@ Examples:
 # Logging in as a user: notch, with a password: password123 onto a server with the ip: mc.someserver.com:25565
 MinecraftClient.exe notch password123 mc.someserver.com:25565
 
-# Overriding a setting from MinecraftClient.ini using a command line parameter
+# Overriding a setting from MinecraftClient.ini using a command-line parameter
 MinecraftClient.exe --debugmessages=false
 
-# Providing a custom settings ini file and overriding a language to Chinese
+# Providing a custom settings file and overriding the language to Chinese
 MinecraftClient.exe CustomSettingsFile.ini --language=zh
 ```
 
 ### Rules of using the command line parameters
 
-You can mix and match arguments by following theses rules:
+You can mix and match arguments by following these rules:
 
 -   First positional argument may be either the login or a settings file
 -   Other positional arguments are read in order: login, password, server, command
@@ -150,7 +152,7 @@ MinecraftClient.exe <login> <password> <server> "/mycommand"
 ```
 
 -   This will automatically send `/mycommand` to the server and close.
--   To send several commands and/or stay connected, use the 1ScriptScheduler1 bot instead.
+-   To send several commands or stay connected, use the `ScriptScheduler` bot instead.
 
 ```bash
 MinecraftClient.exe <myconfig.ini>
@@ -247,7 +249,7 @@ In scripts and remote control, no slash is needed to perform the command, eg. `q
 
     Reports the block type at the given position.
 
-    If you use the `-s` option it will report the types of blocks around the targeted blokcs.
+    If you use the `-s` option, it also reports the surrounding block types.
 
 -   **Usage:**
 
@@ -558,11 +560,11 @@ In scripts and remote control, no slash is needed to perform the command, eg. `q
 
 -   **Description:**
 
-    Reloads settings from MinecraftClient.ini and Chat Bots.
+    Reloads the active configuration file and chat bots.
 
     <div class="custom-container tip"><p class="custom-container-title">Tip</p>
 
-    **Some settings won't be reloaded since they are used before the client initialization. Also, settings provided by the command line paramteres will be overriden. This also does not reload the ReplayBot due to technical limitations.**
+    **Some settings are not reloaded because they are used before client initialization. Settings passed on the command line also override file values. ReplayCapture is not reloaded due to technical limitations.**
 
     </div>
 
@@ -800,7 +802,7 @@ In scripts and remote control, no slash is needed to perform the command, eg. `q
 
     <div class="custom-container tip"><p class="custom-container-title">Tip</p>
 
-    **This command is avaliable only with [Follow Player](chat-bots.md#follow-player) Chat Bot enabled.**
+    **This command is available only when the [Follow Player](chat-bots.md#follow-player) chat bot is enabled.**
 
     </div>
 

docs/guide/websocket/README.md

@@ -1,142 +0,0 @@
-# Web Socket Chat Bot documentation
-
-This is a documentation page on the Web Socket chat bot and on how to make a library that uses web socket to execute commands in the MCC and processes events sent by the MCC.
-
-Please read the [Important things](#important-things) before everything.
-
-# Page index
-
-- [Important things](#important-things)
-  - [Prerequisites](#prerequisites)
-  - [Limitations](#limitations)
-  - [Precision of information](#precisionvalidity-of-the-information-in-this-guide)
-- [How does it work?](#how-does-it-work)
-- [Sending commands](#sending-commands-to-mcc)
-- [Websocket Commands](Commands.md)
-- [Websocket Events](Events.md)
-- [Reference Implementation](#reference-implementation)
-
-## Reference implementation
-
-I have made a reference implementation in TypeScript/JavaScript, it is avaliable here: 
-
-[https://github.com/milutinke/MCC.js](https://github.com/milutinke/MCC.js)
-
-It is great for better understanding how this works.
-
-## Important things
-
-### Prerequisites 
-
-This guide/documentation assumes that you have enough of programming knowledge to know:
-
-  - What Web Socket is
-  - Basics of networking and concurency
-  - What JSON is
-  - What are the various data types such as boolean, integer, long, float, double, object, dictionary/hash map
-
-Without knowing those, I highly recommend learning about those concepts before trying to implement your own library.
-
-### Limitations
-
-The Web Socket chat bot should be considered experimental and prone to change, it has not been fully tested and might change, keep an eye on updates on our official Discord server.
-
-### Precision/Validity of the information in this guide
-
-This guide has been mostly generated from the code itself, so the types are C# types, except in few cases where I have manually changed them. 
-
-For some thing you will have to dig in to the MCC C# code of the Chat Bot and various helper classes.
-
-**Some information sent by the MCC, for example entity metadata, block ids, item ids, or various other data is different for each Minecraft Version, thus you need to map it for each minecraft version.**
-
-Some events might not be that useful, eg. `OnNetworkPacket`
-
-## How does it work?
-
-So, basically, this Web Socket Chat Bot is a chat bot that has a Web Socket server running while you're connected to a minecraft server.
-
-It sends events, and listens for commands and responds to commands.
-
-It has build in authentication, which requires you to send a command to authenticate if the the password is set, if it is not set, it should automatically authenticate you on the first command.
-
-You also can name every connection (session) with an alias.
-
-The flow of the protocol is the following:
-
-```
-Connect to the chat bot via web socket
-
-            |
-            |
-           \ /
-            `
-
-Optionally set a session alias/name with "ChangeSessionId" command 
-(this can be done multiple times at any point)
-
-            |
-            |
-           \ /
-            `
-
-Send an "Authenticate" command if there is a password set 
-
-            |
-            |
-           \ /
-            `
-
-Send commands and listen for events
-```
-
-In order to implement a library that communicates witht this chat bot, you need to make a way to send commands, remember the sent commands via the `requestId` value, and listen for `OnWsCommandResponse` event in which you need to detect if your command has been executed by looking for the `requestId` that matches the one you've sent. I also recommend you put a 5-10 seconds command execution timeout, where you discard the command if it has not been executed in the given timeout range.
-
-## Sending commands to MCC
-
-You can send text in the chat, execute client commands or execute remote procedures (WebSocket Chat Bot commands).
-
-Each thing that is sent to the chat bot results in a response through the [`OnWsCommandResponse`](#onwscommandresponse) event.
-
-### Sending chat messages
-
-To send a chat message just send a plain text with your message to via the web socket.
-
-### Executing client commands
-
-To execute a client command, just send plain text with your command.
-
-Example: `/move suth`
-
-### Execution remote procedures (WebSocket Chat Bot commands)
-
-In order to execute a remote procedure, you need to send a json encoded string in the following format:
-
-```json
-{
-  "command": "<command name here>",
-  "requestId": "<randomly generated string for identification>",
-  "parameters": [ 1, "some string", true, "etc.." ]
-}
-```
-
-#### `command` 
-
-  Refers to the name of the command
-
-#### `requestId`
-
-  Is a unique indentifier you generate on each command, it will be returned in the response of the command execution ([`OnWsCommandResponse`](#onwscommandresponse)), use it to track if a command has been successfully executed or not, and to get the return value if it has been successfully executed. (*It's recommended to generate at least 7 characters to avoid collision, best to use an UUID format*).
-
-#### `parameters`
-  
-  Are parameters (attibutes) of the procedure you're executing, they're sent as an array of data of various types, the Web Socket chat bot does parsing and conversion and returns an error if you have sent a wrong type for the given parameters, of if you haven't send enough of them.
-
-  **Example:**
-
-  ```json
-  {
-    "command": "Authenticate",
-    "requestId": "8w9u60-q39ik",
-    "parameters": ["wspass12345"]
-  }
-  ```

docs/package.json

@@ -7,18 +7,23 @@
   "license": "CDDL-1.0",
   "private": false,
   "scripts": {
-    "docs:build": "vuepress-cli build --clean-cache",
+    "docs:build": "vuepress build . --clean-cache",
     "docs:clean": "rimraf .vuepress/.temp .vuepress/.cache .vuepress/dist",
-    "docs:dev": "vuepress-cli dev --clean-cache",
+    "docs:dev": "vuepress dev . --clean-cache",
     "docs:serve": "anywhere -s -h localhost -d .vuepress/dist"
   },
   "devDependencies": {
-    "@vuepress/bundler-webpack": "^2.0.0-beta.53",
+    "@vuepress/bundler-vite": "2.0.0-rc.26",
-    "@vuepress/plugin-search": "^2.0.0-beta.53",
+    "@vuepress/bundler-webpack": "2.0.0-rc.26",
-    "@vuepress/plugin-shiki": "^2.0.0-beta.53",
+    "@vuepress/plugin-markdown-chart": "2.0.0-rc.125",
-    "vuepress": "^2.0.0-beta.53",
+    "@vuepress/plugin-redirect": "2.0.0-rc.125",
-    "vuepress-plugin-mermaidjs": "2.0.0-beta.2",
+    "@vuepress/plugin-search": "2.0.0-rc.125",
-    "vuepress-plugin-redirect": "^2.0.0-beta.120"
+    "@vuepress/plugin-shiki": "2.0.0-rc.125",
+    "@vuepress/theme-default": "2.0.0-rc.125",
+    "mermaid": "11.13.0",
+    "sass-embedded": "1.98.0",
+    "sass-loader": "16.0.7",
+    "vuepress": "2.0.0-rc.26"
   },
   "dependencies": {
     "anywhere": "^1.6.0"

tools/mcc-env.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 # MCC (Minecraft Console Client) Development Utilities
 # Source this file to get helper functions: source $MCC_REPO/tools/mcc-env.sh
-# Or add to ~/.bashrc:  source "$HOME/Minecraft/Minecraft-Console-Client-milutinke/tools/mcc-env.sh"
+# Or add to ~/.bashrc:  source "$HOME/Minecraft/Minecraft-Console-Client/tools/mcc-env.sh"
 
 TOOLS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 export MCC_REPO="$(cd "$TOOLS_DIR/.." && pwd)"

tools/pull-translations.sh

@@ -0,0 +1,66 @@
+#!/bin/bash
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+CONFIG_FILE="$REPO_ROOT/crowdin.yml"
+TMP_CONFIG=""
+
+if [[ -z "${CROWDIN_PERSONAL_TOKEN:-}" && -n "${CROWDIN_TOKEN:-}" ]]; then
+    export CROWDIN_PERSONAL_TOKEN="$CROWDIN_TOKEN"
+fi
+
+if [[ ! -f "$CONFIG_FILE" ]]; then
+    echo "Error: crowdin.yml not found at $CONFIG_FILE" >&2
+    exit 1
+fi
+
+if [[ -z "${CROWDIN_PROJECT_ID:-}" ]]; then
+    echo "Error: CROWDIN_PROJECT_ID is not set" >&2
+    exit 1
+fi
+
+if [[ -z "${CROWDIN_PERSONAL_TOKEN:-}" ]]; then
+    echo "Error: CROWDIN_PERSONAL_TOKEN is not set" >&2
+    echo "Tip: the CI workflow stores this as CROWDIN_TOKEN and maps it to CROWDIN_PERSONAL_TOKEN." >&2
+    exit 1
+fi
+
+run_crowdin() {
+    "$@" download translations --all --config "$CONFIG_FILE"
+}
+
+cleanup() {
+    if [[ -n "$TMP_CONFIG" && -f "$TMP_CONFIG" ]]; then
+        rm -f "$TMP_CONFIG"
+    fi
+}
+trap cleanup EXIT
+
+make_temp_config() {
+    local base_path="$1"
+    TMP_CONFIG="$(mktemp "$REPO_ROOT/.crowdin.local.XXXXXX.yml")"
+    sed "s#\"base_path\": \"/\"#\"base_path\": \"$base_path\"#" "$CONFIG_FILE" > "$TMP_CONFIG"
+}
+
+cd "$REPO_ROOT"
+
+if command -v crowdin >/dev/null 2>&1; then
+    echo "Using local Crowdin CLI"
+    make_temp_config "$REPO_ROOT"
+    crowdin download translations --all --config "$TMP_CONFIG"
+elif command -v docker >/dev/null 2>&1; then
+    echo "Using Crowdin CLI via Docker"
+    make_temp_config "/work"
+    docker run --rm \
+        --entrypoint crowdin \
+        -e CROWDIN_PROJECT_ID \
+        -e CROWDIN_PERSONAL_TOKEN \
+        -v "$REPO_ROOT":/work \
+        -w /work \
+        crowdin/cli:latest \
+        download translations --all --config /work/"$(basename "$TMP_CONFIG")"
+else
+    echo "Error: neither 'crowdin' nor 'docker' is available" >&2
+    echo "Install Crowdin CLI or Docker and try again." >&2
+    exit 1
+fi