katrain-qt/AGENTS.md

KaTrain Qt Port

This repository is a Qt 6 port of KaTrain, a KataGo frontend for Go/Baduk.

Repository Context

• The port starts from upstream KaTrain 1.19.0.
• Development currently happens on qt-0.19.0, which presently matches upstream v0.19.0.
• ../katrain-reference is a read-only checkout of upstream KaTrain 1.19.0. Use it to compare behavior and implementation, but never modify it.
• Make all changes in this repository on qt-0.19.0.

Porting Direction

• Upstream KaTrain is a Python application built with Kivy.
• Kivy does not work well on Wayland, so this project is a Qt 6 port.
• The goal is a PySide6 frontend for KaTrain.
• katrain/core is not fully UI-independent. The first major goal is to separate the actual core functionality from UI-specific concerns before or alongside the Qt UI port.
• Preserve upstream behavior where practical, while keeping UI abstractions out of the reusable core.
• Do not rewrite working core logic unless necessary. Keep divergence small so upstream versions can continue to be tracked.

Scope

Non-goals

• Engine or model downloading.
• KataGo contribution.
• Mobile support.
• Kivy compatibility in the new frontend.
• Sabaki theme package installation.

Required Functionality

• SGF loading and saving.
• KataGo analysis.
• Analysis graph, move tree, candidate moves, ownership display, and principal variation display.
• Mistake coloring.
• Play against AI.
• Teaching and training modes.
• Human-like AI settings.
• Engine restart and settings.
• Localization, where practical.

Board Themes

• Support arbitrary board texture, black stone, and white stone images.
• Allow board, black stone, and white stone components to be mixed independently.
• Support multiple stone image variants internally.

Environment

• Development environment: Gentoo Linux with OpenRC.
• Shell: Zsh.
• Git pushes to origin are available.

Git Workflow

• Push development work only to origin/qt-0.19.0.
• Do not merge directly into main.
• Merge to main only through a pull request after reaching a meaningful milestone.
• Use commit-message prefixes such as FEAT:, FIX:, MINOR:, or STYLE:.