# ALCOMD3 maintenance notes

Languages: English | [日本語](MAINTENANCE.ja.md) | [简体中文](MAINTENANCE.zh-CN.md)

These notes document ALCOMD3's current project behavior, compatibility
boundaries, and maintenance decisions. Use them when changing ALCOMD3 code or
when selectively importing fixes from any external source.

### Branding

ALCOMD3 uses its own branding while keeping compatibility points required by
existing installations.

- Product and visible app name: `ALCOMD3`.
- Window title: `ALCOMD3`.
- Windows installer display name: `ALCOMD3`.
- Windows shortcuts: `ALCOMD3`.
- Windows setup output name: `alcomd3-{version}-setup.exe`.
- The installed main executable keeps its legacy file name for compatibility
  with the existing install path, protocol associations, and updater/install migration.
- The Windows installer updates the existing application installation instead
  of installing side by side.
- The `vcc://` URL shortcut association defaults to enabled when no explicit
  user choice exists.

Important files:

- `vrc-get-gui/Tauri.toml`
- `vrc-get-gui/src/commands/start.rs`
- `vrc-get-gui/src/commands/util.rs`
- `vrc-get-gui/src/config.rs`
- `vrc-get-gui/bundle/windows-setup.iss`
- `xtask/src/bundle_alcom.rs`
- `xtask/src/bundle_alcom/setup_exe.rs`

### Startup and window display

Preserve these behaviors:

- Saved initial window size and maximized state are applied when the main window
  is created.
- The main window starts hidden and is shown by the backend after the frontend
  calls the frontend-ready command.
- `index.html` keeps a static first-frame background color so startup does not
  flash pure white before CSS and JavaScript load.
- Startup checks reject unsupported non-ASCII host names before normal UI startup.

### Material Design 3 UI

Preserve these behaviors:

- The Material Theme entry is visible in the side navigation.
- The side navigation can show optional BOOTH, VRChatAvatarLearn, and version
  buttons. They can be hidden with `hide_sidebar_links`.
- The version button displays `version: v{actual_version}` and copies
  `v{actual_version}`.
- Toasts use rounded MD3 styling, MD3 semantic progress colors, and the app base
  background color.
- Important project/package actions use ALCOMD3 emphasis button styling.
- Setup and settings copy use `ALCOMD3` in user-facing text.

Important areas:

- `vrc-get-gui/app`
- `vrc-get-gui/components`
- `vrc-get-gui/app/globals.css`
- `vrc-get-gui/lib/material-theme.ts`
- `vrc-get-gui/locales/*.json5`
- `vrc-get-gui/src/config.rs`

### Icons and third-party notices

The app icon uses the ALCOMD3 theme color `#6cb6ff` and is covered by the
project's third-party asset notices.

- Keep the full logo design when regenerating icons.
- Do not replace small icon sizes with a simplified variant unless that is an
  explicit design decision.
- Keep `vrc-get-gui/THIRD-PARTY.md` accurate.
- The in-app Licenses page is generated by
  `vrc-get-gui/scripts/vite-build-license-json.ts`.

Important assets:

- `vrc-get-gui/app-icon.png`
- `vrc-get-gui/icons/*`
- `vrc-get-gui/icon-LICENSE`
- `vrc-get-gui/third-party/Anton-Regular-OFL.txt`
- `vrc-get-gui/third-party/NotoSans-OFL.txt`

### Package operations

ALCOMD3 owns package operation progress and cancellation behavior.

Preserve these behaviors:

- Installing, removing, and reinstalling packages show a progress dialog.
- The dialog shows per-package status, overall progress, and success/failure counts.
- Failed packages can be retried.
- Long-running operations can be terminated by the user.
- Closing the main window during an operation requests termination instead of
  immediately closing the app.
- Termination must not turn already successful packages into failed items.
- Parallel package work should continue where possible; one package failure
  should not unnecessarily stop unrelated packages.

Backend rules:

- `AbortCheck` is shared between frontend cancellation, window-close
  interception, package download, package extraction, and package apply steps.
- Download/cache verification and zip extraction check cancellation between copy chunks.
- Package install/remove/reinstall progress is reported through
  `TauriProjectApplyProgress`.
- Partial package failures are collected and reported while successful packages
  can still finish.

Important areas:

- `vrc-get-gui/app/_main/projects/manage`
- `vrc-get-gui/src/commands/project.rs`
- `vrc-get-gui/src/commands/start.rs`
- `vrc-get-gui/src/state/project_apply.rs`
- `vrc-get-vpm/src/traits.rs`
- `vrc-get-vpm/src/environment/package_installer.rs`
- `vrc-get-vpm/src/unity_project/pending_project_changes.rs`
- `vrc-get-vpm/src/utils/extract_zip.rs`

### Project copy, backup, and restore

Preserve these behaviors:

- Project copy shows progress and can be canceled.
- Backup and restore workflows report progress instead of appearing stalled.
- Main-window close handling coordinates with active long-running operations
  instead of allowing silent interruption.

Important areas:

- `vrc-get-gui/app/_main/projects`
- `vrc-get-gui/src/commands/project.rs`
- `vrc-get-gui/src/commands/start.rs`

### Repository management

Preserve ALCOMD3 repository-management features:

- Repository ordering / priority adjustment.
- Viewing the package list contained in a repository.

When importing package or repository-management changes from any source,
preserve these features.

Important areas:

- `vrc-get-gui/app/_main/packages/repositories`
- `vrc-get-gui/components/ReorderableList.tsx`

### MCP bridge

ALCOMD3 includes an optional local MCP bridge. Preserve the minimal read-only
boundary unless a future change explicitly expands it with review and UI
approval flows.

Preserve these rules:

- MCP data access is disabled by default and must be enabled from the GUI before
  tools return ALCOMD3 data.
- The external MCP server is `alcomd3-mcp` over stdio.
- stdout from `alcomd3-mcp` must contain only MCP JSON-RPC messages; diagnostics
  belong on stderr.
- The GUI exposes a private localhost TCP IPC endpoint while running and writes
  metadata under the local data directory's `mcp/endpoint.json`.
- The GUI MCP enable/disable control only gates tool data access. It must not
  stop the local endpoint; disabled tool calls return `mcp_disabled`.
- `ALCOMD3_MCP_ENDPOINT_FILE` may override the endpoint metadata path for
  development and tests.
- Tools are read-only: list projects, get registered project details, list
  repositories, and search already loaded packages.
- `project_path` must match an ALCOMD3 registered project before details are read.
- MCP package search must not force repository refreshes.
- `initialize` and `tools/list` must not start the GUI.
- Actual tool calls may start the GUI when the endpoint is unavailable. The
  bridge should start only the packaged/sibling ALCOMD3 GUI executable or the
  explicit `ALCOMD3_GUI_EXECUTABLE` override.
- `alcomd3-mcp` must not install, update, or repair the GUI.
- GUI shutdown should remove the endpoint file.

Important areas:

- `docs/mcp.md`
- `alcomd3-mcp/`
- `alcomd3-mcp-protocol/`
- `vrc-get-gui/src/mcp.rs`
- `vrc-get-gui/src/commands/mcp.rs`
- `vrc-get-gui/app/_main/mcp/index.tsx`
- `xtask/src/build_alcom.rs`
- `xtask/src/bundle_alcom.rs`

### Updater and release

ALCOMD3 uses its own update source and signing key.

Preserve these rules:

- Stable endpoint: `https://alcomd3.cqmhv.com/api/gui/tauri-updater.json`.
- Beta endpoint: `https://alcomd3.cqmhv.com/api/gui/tauri-updater-beta.json`.
- Update-available dialogs include an official website action that opens
  `https://alcomd3.cqmhv.com/`.
- Automatic update check failures stay silent for users.
- Manual update checks show dialogs for both no-update and failed-update results.
- Versions use SemVer strings such as `2.1.0-beta.1`.
- The updater private key must stay out of git.
- Follow `docs/RELEASE.md` and `docs/ALCOMD3_UPDATER.md` when signing updater
  installers.
- Before publishing website updater JSON, run `cargo xtask verify-alcom-updater-json`
  for each JSON file that will be served.

### Windows installer

Preserve these rules:

- Installer product name is `ALCOMD3`.
- Output setup file uses `alcomd3` and includes the version.
- `VersionInfoProductVersion` uses a Windows-compatible numeric version.
- Setup icon uses `vrc-get-gui/icons/icon.ico`.
- Legacy desktop/start menu shortcuts are removed during install.
- The installed main executable keeps its legacy file name.

### GitHub configuration

Generic inherited GitHub workflows were removed intentionally. ALCOMD3 release
automation should be rebuilt explicitly for this repository when needed.

Preserve:

- `.github/ISSUE_TEMPLATE/*`

No GitHub release workflow or signing action is currently maintained in the
repository. Local release automation is maintained through
`cargo xtask release-*`; see `docs/RELEASE.md`.

Removed intentionally:

- `.github/actions/sign-windows/action.yml`
- `.github/workflows/*`
- `.github/dependabot.yml`
- `.github/labeler.yml`
- `.github/scripts/*`
- `.github/copilot-instructions.md`

### Release notes and local build commands

- Current stable release note: `release-notes/ALCOMD3_2.0.0.md`.
- Current beta release note: `release-notes/ALCOMD3_2.0.1-beta.1.md`.
- Previous release notes are kept under `release-notes/`.
- Future release notes should focus on user-visible ALCOMD3 changes.

Windows release build:

```powershell
cargo xtask release-build --version 2.0.1 --channel stable
```

Expected outputs:

- `artifacts/release/v{version}/alcomd3-{version}-setup.exe`
- `artifacts/release/v{version}/alcomd3-{version}-setup.exe.sig`
- `artifacts/release/v{version}/alcomd3-{version}-setup.exe.zip`

Known non-blocking warnings:

- `xtask/src/bundle_alcom/linux.rs` may warn about an unused `mode` variable.
- Vite may warn that `vrc-get://localhost/global-info.js` cannot be bundled
  without `type="module"`.
