ai_coc 0.2.1__tar.gz

ai_coc-0.2.1/.gitignore

@@ -0,0 +1,238 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer,
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+/data/
+/docs/
+TODO.md
+
+# Secrets and local configuration
+.env.*
+!.env.example
+*.key
+*.pem
+*.p12
+secrets/
+config/settings.json
+
+# Private runtime/account data. COC_LIVE_TEST_SCREENSHOT and COC_AGENT_SCREENSHOT
+# write frames of a live account wherever they are pointed.
+data/accounts/
+data/runtime/
+screenshots/
+captures/
+adbkey
+adbkey.pub

ai_coc-0.2.1/CLAUDE.md

@@ -0,0 +1,81 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+A Windows-only PyQt5 desktop application that drives Clash of Clans running inside MuMu Player 12. Gemini does the semantic screen reading; the app turns its answers into ADB taps and verifies the outcome on the next screenshot. Live battle tactics are deliberately out of scope: `battle.py` validates army requirements and stops at a reserved `RESERVED_RL` handoff boundary.
+
+## Development flow
+
+Read `gh-dev-flow` before starting; it owns the path from a task landing to the change being merged. In this repo that path always ends the same way: open the PR as a draft, run `code-review` over the branch and fix what holds up, then merge once CI is green. Merging on green needs no further approval.
+
+## Commands
+
+```bash
+uv sync --group test                 # the suite needs the `test` group
+uv run pytest                        # full suite (xdist, coverage gate, JUnit/XML into .github/reports)
+uv run pytest tests/test_core.py::CoreTests::test_battle_script_requires_army   # single test
+make fmt                             # pre-commit: ruff, mdformat, codespell, ty, gitleaks, uv-sync/lock
+make gen-docs                        # rebuild docs/ from the READMEs and the source
+```
+
+Run the app with `uv run ai_coc`. Two CLI hooks exist for smoke tests: `--live-test` captures a frame and asks Gemini to describe it, and `--agent-command=<text>` types a command into the AI tab and executes it. Both save a proof screenshot of the window when `COC_LIVE_TEST_SCREENSHOT` / `COC_AGENT_SCREENSHOT` point at a path.
+
+Distributables are built in CI only: pushing a `v*` tag runs `build_release.yml`, which publishes the wheel to PyPI and attaches a PyInstaller Windows build to the release. There is no local build script.
+
+That build defaults to `--onedir`, and the dispatch form's `package_mode` switches it to `--onefile`. Measured here, onefile costs 6.6-7.0 s to reach the first log line against onedir's 1.4-3.1 s, because it unpacks the whole bundle into a temp directory on every launch. Onefile is one 76 MB file where onedir is a 174 MB folder, so it stays available, just not the default.
+
+## Architecture
+
+`src/ai_coc/cli.py` is the entry point behind both console scripts (`ai_coc` and `cli`) and the PyInstaller build. PyInstaller runs it as `__main__`, so its imports stay absolute even for same-layer modules and it keeps an `if __name__ == "__main__"` block.
+
+The three layers are directories, so an import that crosses them is visible in the import line:
+
+- **UI and orchestration** — `ui/main_window.py` (`MainWindow`), all seven tabs plus every workflow; `ui/workers.py` (thread-pool workers and the log handler); `ui/render.py` (Markdown and log records to HTML). `cli.py` is only `main()`.
+- **Adapters** — `adapters/mumu.py` (emulator lifecycle), `adapters/adb.py` (every ADB call), `adapters/ai.py` (Gemini), `adapters/secrets.py` (DPAPI), `adapters/database.py` (SQLite).
+- **Pure parsers** — `parsers/village.py`, `parsers/battle.py`.
+- **Data shapes** — `models.py` at the package root holds every Pydantic model in the project; see the Pydantic rule below.
+
+Imports across layers are absolute (`from ai_coc.models import …`) and within a layer relative (`from .adb import …`); Ruff's `TID252` enforces it and rewrites the rest.
+
+**Threading.** Every blocking call goes through `MainWindow.run_async`, which wraps the callable in a `Worker` (`QRunnable`) on the global `QThreadPool` and delivers the result back to the UI thread via `pyqtSignal`. A call that produces text as it goes uses `MainWindow.run_stream` and a `StreamWorker` instead: it drains a generator and emits each chunk. Never call `MuMuAdapter` or `GeminiClient` directly from a slot.
+
+**The AI 助手 transcript is a model, not a text buffer.** `MainWindow.chat` is a `ChatTranscript`; `_say` appends a `ChatMessage` and `_paint_chat` re-renders the whole transcript into the `QTextBrowser` through `ui/render.py`. Bodies are Markdown, rendered by `markdown-it-py` with raw HTML disabled, and styled by `CHAT_STYLESHEET` (Qt honours only a subset of CSS 2.1). A streamed reply grows the last message in place, and repaints are throttled by the `chat_repaint` timer rather than fired per token.
+
+**Logging.** `configure_logging()` in `main()` sets up a rotating plain-text file at `~/.ai_coc\logs\controller.log` plus a `rich` stderr console; `MainWindow._attach_log_panel` adds a handler that renders every record through `rich` and mirrors the resulting HTML into the 執行紀錄 panel under the tabs, and the panel's level selector retargets the root logger at runtime (DEBUG adds full prompts and replies). The file handler stays plain text so the log can still be grepped. `Worker.run` logs the traceback before the message box, and `sys.excepthook` catches what Qt would otherwise swallow. New adapter code is expected to log its own decisions; a feature that fails silently is the bug being fixed here.
+
+**Agent loop** (`execute_agent_command`): ensure CoC is running, then loop up to `max_steps` (8 normally, 25 when the command mentions 進攻/戰鬥/搜尋資源村). Each step captures a screenshot plus a `uiautomator dump`, sends both to Gemini and reads back an `AgentAction` through structured output, applies it, sleeps 2 s and re-observes. Anything outside `tap|back|swipe_up|swipe_down` ends the task, so a new action verb needs a `Literal` member on `AgentAction`, a branch in `_apply_agent_action` and a mention in the prompt.
+
+**Authorization is prompt-level only.** The automation-tab checkboxes are interpolated into the prompt as 自主升級／刷牆／自主進攻 flags, and the prompt forbids gems, cash, deletion and account operations. Nothing below the prompt enforces this. Treat any new capability that spends resources as needing its own guard in code.
+
+**Task durability.** Every agent command becomes a row in `tasks`. A task left `PENDING` is picked up again by `resume_pending_tasks` shortly after startup and after each completion, and `automation_cycle` refuses to queue new work while one is running.
+
+**Coordinates are hard-coded to 1600x900.** Gemini returns percentages, and `_apply_agent_action` converts them with `x_pct * 16, y_pct * 9`. Any other instance resolution taps the wrong place. Related known quirk: ADB `wm size` reports 900x1600 while the screenshot arrives as 1600x900.
+
+**`MuMuAdapter`** uses `mumu-cli.exe` (JSON output) for discovery and lifecycle only; every capture and input goes through `adb.py`. Two rules were paid for in bugs, do not undo them:
+
+- `_clean_environment` strips `QT_PLUGIN_PATH` and friends from every subprocess, because the PyInstaller bundle's Qt plugin paths break mumu-cli, which is itself a Qt application.
+- `ensure_coc` escalates launch → poll → restart instance, because MuMu reports Android ready before a `monkey` launch will reliably stick.
+
+**`adb.py` owns ADB.** `AdbController` wraps `adbutils`, one instance per serial, and `MuMuAdapter.controller()` caches them — that is how several emulators coexist, since each MuMu instance publishes its own port (`AdbEndpoint`, port 0 meaning not listening yet). `use_adb_executable` points `ADBUTILS_ADB_PATH` at MuMu's own `nx_main\adb.exe` so the adb server matches the emulator. Do not shell out to `adb.exe` from anywhere else.
+
+**Every capture and every input names a display.** MuMu runs several Android displays and opens the game on one of its own, leaving display 0 on the emulator's launcher. Unqualified, `screencap -p` prefixes the PNG with a multi-display warning and the decode fails, while `input tap` silently lands on the launcher. `AdbController.display_for(package)` finds the right one and returns a `DisplayTarget`; `screencap -d` takes its physical id and `input -d` its logical id, because MuMu numbers the two schemes apart. Do not drop the `-d` flags.
+
+**`GeminiClient`** is the only place the app talks to Gemini, through the `google-genai` SDK's Interactions API. Every request body is a `GeminiRequest`, never a hand-built dict. `generate` returns the whole text; `stream` sets `stream=True` and yields the `step.delta` text events, which is what the chat and the screen analysis use; `generate_structured(prompt, SomeModel, png)` sets `response_format` from the model's JSON schema and returns the validated instance, so no code strips ```` ```json ```` fences by hand. Structured output cannot stream, so the agent loop stays on `generate_structured`. `list_text_models` feeds the Model picker in Settings and only appears after 測試連線 succeeds. The default model is `DEFAULT_GEMINI_MODEL` in `constants.py`.
+
+**Storage** lives in `~/.ai_coc\`: `controller.sqlite3`, `frames/`, `account_json/` and the DPAPI-protected `gemini.key.dpapi`. The schema is created idempotently in `Database._initialize` with no migration tooling, so a changed table means bumping `SCHEMA_VERSION` and handling existing databases yourself. The API key never goes into `QSettings`, only into the DPAPI file.
+
+**Village and Battle Script parsing is deliberately tolerant.** Unknown sections and fields are preserved verbatim, unknown `data_id`s are queued into `unknown_entities` instead of failing the import. Game updates add IDs; keep it tolerant.
+
+## Project rules
+
+- **Every structured value is a Pydantic `BaseModel`, no exceptions.** New shapes go in `models.py`: emulator and CLI payloads, database rows, parsed files, AI replies, requests, settings and the chat transcript. The adapters are models too (`Database`, `SecretStore`, `AdbController`, `MuMuAdapter`, `GeminiClient`), so they take keyword arguments and put their non-field state in `PrivateAttr`. Only Qt subclasses and the ctypes `DATA_BLOB` stay plain classes, because their base class rules it out. Do not introduce a `dataclass`, a `TypedDict`, or a bare `dict[str, Any]` that travels between functions, and do not read a value out with `.get("key")` when a model could have declared the field — historical key names belong in `AliasChoices`, not in an `or` chain. Parse at the boundary with `model_validate` / `model_validate_json`, and write JSON out with `model_dump_json()` / `model_dump()` rather than `json.dumps` over a hand-built dict; a bare list on its way into a prompt gets a `RootModel` (`UiElementList`, `AccountRowList`). Ask Gemini for structure through `GeminiClient.generate_structured` and a model, never by parsing the text yourself. Models mirroring an external format that gains fields between releases carry `model_config = TOLERANT` so unknown keys survive.
+- **A model field's type must be importable at runtime.** `[tool.ruff.lint.flake8-type-checking] runtime-evaluated-base-classes` keeps `TC003` from moving those imports into `if TYPE_CHECKING`, which would leave the model unbuildable. If a new model base class appears, add it there.
+- **Never invent master data.** `entity_levels` (costs, times, requirements) stays empty until a value is source-backed, and the UI shows `—` rather than a guess. This is a stated product decision, not an oversight.
+- **`docs/` is generated and gitignored**, rebuilt from the three READMEs and the source by `make gen-docs`. Edit the READMEs and the docstrings, never the generated output.
+- **UI strings, prompts and user-facing messages are Traditional Chinese**; code, comments, commit messages and anything published to GitHub are English.
+- **Deliberate deviations from the repo template**, documented in `pyproject.toml` comments: coverage gate is `--cov-fail-under=12` because almost everything is the untested PyQt shell; `[tool.ty.environment] python-platform = "win32"` is required or `winreg`/`ctypes.windll` fail to resolve on Linux CI runners; ty excludes `cli.py`, `ui/main_window.py` and `ui/workers.py` because PyQt5 ships inaccurate stubs; `allowed-confusables` carries `／` and `？` for the Chinese UI strings; the `build_release.yml` matrix is Windows-only because nothing here runs elsewhere.
+- **The version is never written down.** `constants.py` reads it from the installed package metadata, and CI derives that from the git tag through `dunamai`. The `0.1.0` in `pyproject.toml` is a placeholder CI overwrites; do not hand-edit a version anywhere else.
+- **Package data lives inside the package.** `battle_scripts/` sits at `src/ai_coc/battle_scripts/` and is reached through `BATTLE_SCRIPT_DIR`, so a wheel install resolves it the same way a source checkout does. The PyInstaller step needs `--add-data` for it and `--copy-metadata` for the version lookup; both are in `build_release.yml`.
+- CodeQL and dependency-review jobs are gated on `github.event.repository.visibility == 'public'` because this private repo has no GitHub Advanced Security.

ai_coc-0.2.1/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 CoC AI Controller contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

ai_coc-0.2.1/PKG-INFO

@@ -0,0 +1,226 @@
+Metadata-Version: 2.5
+Name: ai_coc
+Version: 0.2.1
+Summary: AI-driven Clash of Clans automation controller for MuMu Player on Windows
+Project-URL: Homepage, https://mai0313.github.io/ai_coc
+Project-URL: Repository, https://github.com/Mai0313/ai_coc
+Author-email: Wei <mai@mai0313.com>
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: adbutils>=2.10
+Requires-Dist: defusedxml<1,>=0.7
+Requires-Dist: google-genai>=2.3.0
+Requires-Dist: markdown-it-py>=3.0
+Requires-Dist: pydantic>=2.9
+Requires-Dist: pyqt5-qt5==5.15.2; sys_platform == 'win32'
+Requires-Dist: pyqt5<6,>=5.15
+Requires-Dist: rich>=13.9
+Description-Content-Type: text/markdown
+
+<div align="center" markdown="1">
+
+# AI CoC
+
+[![PyPI version](https://img.shields.io/pypi/v/ai_coc.svg)](https://pypi.org/project/ai_coc/)
+[![python](https://img.shields.io/badge/-Python_%7C_3.12%7C_3.13%7C_3.14-blue?logo=python&logoColor=white)](https://www.python.org/downloads/source/)
+[![uv](https://img.shields.io/badge/-uv_dependency_management-2C5F2D?logo=python&logoColor=white)](https://docs.astral.sh/uv/)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![ty](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ty/main/assets/badge/v0.json)](https://github.com/astral-sh/ty)
+[![Pydantic v2](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/pydantic/pydantic/main/docs/badge/v2.json)](https://docs.pydantic.dev/latest/contributing/#badges)
+[![tests](https://github.com/Mai0313/ai_coc/actions/workflows/test.yml/badge.svg)](https://github.com/Mai0313/ai_coc/actions/workflows/test.yml)
+[![code-quality](https://github.com/Mai0313/ai_coc/actions/workflows/code-quality-check.yml/badge.svg)](https://github.com/Mai0313/ai_coc/actions/workflows/code-quality-check.yml)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/Mai0313/ai_coc)
+[![license](https://img.shields.io/badge/License-MIT-green.svg?labelColor=gray)](https://github.com/Mai0313/ai_coc/tree/main?tab=License-1-ov-file)
+[![PRs](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/Mai0313/ai_coc/pulls)
+[![contributors](https://img.shields.io/github/contributors/Mai0313/ai_coc.svg)](https://github.com/Mai0313/ai_coc/graphs/contributors)
+
+</div>
+
+A Windows desktop application that drives Clash of Clans running inside MuMu Player 12. Gemini reads the screen; the app turns its answers into ADB taps and verifies the outcome on the next screenshot.
+
+Other Languages: [English](README.md) | [繁體中文](README.zh-TW.md) | [简体中文](README.zh-CN.md)
+
+## ✨ What it does
+
+- Detects MuMu Player 12 instances, starts the emulator and launches the game
+- Captures the screen over ADB and asks Gemini what is on it, with structured replies validated through Pydantic
+- Runs an agent loop that taps, swipes and goes back, re-observing after every step
+- Imports village JSON exports and battle scripts, keeping unknown fields and unknown `data_id`s instead of failing on them
+- Persists every agent command as a task, so an interrupted run is picked up again on the next start
+- Stores the Gemini API key through Windows DPAPI, never in plain settings
+
+Live battle tactics are deliberately out of scope: battle scripts are validated for army requirements and stop at a reserved handoff boundary.
+
+## 📋 Requirements
+
+- Windows. The app talks to `mumu-cli.exe`, reads the registry through `winreg` and calls DPAPI through `ctypes.windll`, none of which exist elsewhere
+- [MuMu Player 12](https://www.mumuplayer.com/) with Clash of Clans installed, running at 1600x900
+- A Gemini API key, entered in the app's settings tab
+
+## 🚀 Install and run
+
+From PyPI, without installing anything permanently:
+
+```bash
+uvx ai_coc
+```
+
+Or as a regular install:
+
+```bash
+uv tool install ai_coc
+ai_coc
+```
+
+Prebuilt Windows executables are attached to every [release](https://github.com/Mai0313/ai_coc/releases).
+
+## 🛠️ Local development
+
+```bash
+git clone https://github.com/Mai0313/ai_coc.git
+cd ai_coc
+uv sync --group test          # install dependencies
+uvx pre-commit install        # install git hooks
+uv run ai_coc                 # start the app
+```
+
+Two command-line hooks exist for smoke tests. `--live-test` captures a frame and asks Gemini to describe it; `--agent-command=<text>` types a command into the AI tab and runs it. Both save a proof screenshot when `COC_LIVE_TEST_SCREENSHOT` / `COC_AGENT_SCREENSHOT` point at a path.
+
+## 🧰 Commands Reference
+
+```bash
+# Development
+make help               # List available make targets
+make clean              # Clean caches, artifacts and generated docs
+make fmt                # Run all pre-commit hooks
+make test               # Run pytest across the repository
+make gen-docs           # Generate docs from src/ and scripts/
+
+# Dependencies (via uv)
+make uv-install         # Install uv on your system
+uv add <pkg>            # Add production dependency
+uv add <pkg> --dev      # Add development dependency
+# Sync optional groups
+uv sync --group dev     # Install dev-only deps (pre-commit, poe, notebook)
+uv sync --group test    # Install test-only deps
+uv sync --group docs    # Install docs-only deps
+```
+
+## 🧱 Architecture
+
+The three layers are directories, so an import that crosses them is visible in the import line:
+
+- **UI and orchestration** — `ui/main_window.py` holds the window and every workflow, `ui/workers.py` the thread-pool workers, `ui/render.py` the Markdown and log rendering. `cli.py` is only `main()`
+- **Adapters** — `adapters/mumu.py` (emulator lifecycle), `adapters/adb.py` (every ADB call), `adapters/ai.py` (Gemini), `adapters/secrets.py` (DPAPI), `adapters/database.py` (SQLite)
+- **Pure parsers** — `parsers/village.py`, `parsers/battle.py`
+
+Every structured value is a Pydantic model, collected in `models.py`. Blocking calls go through a `QThreadPool` worker and come back to the UI thread as a signal.
+
+Application state lives in `~/.ai_coc`: the SQLite database, captured frames, imported account JSON and the DPAPI-protected key file.
+
+## 📚 Documentation
+
+Documentation is built with [Zensical](https://zensical.org/) and auto-generated from source code via `scripts/gen_docs.py`.
+
+```bash
+uv sync --group docs
+make gen-docs                  # generate markdown from source
+uv run zensical serve          # http://0.0.0.0:9987
+```
+
+`make gen-docs` recreates `docs/`, copies the three READMEs in, then runs `gen_docs.py` over `./src` and `./scripts`.
+
+## 📦 Packaging and Distribution
+
+Build artifacts with uv (wheel and sdist go to `dist/`):
+
+```bash
+uv build
+```
+
+Publish to PyPI (requires `UV_PUBLISH_TOKEN`):
+
+```bash
+UV_PUBLISH_TOKEN=... uv publish
+```
+
+Pushing a `v*` tag runs `build_release.yml`, which derives the version from git via `dunamai`, builds the wheel and sdist, publishes to PyPI, packages a Windows build with PyInstaller and attaches everything to the GitHub Release.
+
+That build is `--onedir` by default: the zip holds the executable next to an `_internal/` folder, which starts several seconds faster than a single-file build that has to unpack itself on every launch. Running the workflow by hand offers a `package_mode` choice if you want the single `.exe` instead.
+
+## 🧭 Optional task runner (Poe the Poet)
+
+Convenience tasks are defined under `[tool.poe.tasks]` in `pyproject.toml` and available after installing the dev group (`uv sync --group dev`) or via `uvx`:
+
+```bash
+uv run poe docs        # generate + serve docs (requires dev group)
+uv run poe gen         # generate + deploy docs (gh-deploy) (requires dev group)
+uv run poe main        # run the app (same as uv run ai_coc)
+
+# or ephemeral via uvx (no local install)
+uvx poe docs
+```
+
+## 🔁 CI/CD Actions Overview
+
+All workflows live in `.github/workflows/`.
+
+- Tests (`test.yml`)
+
+    - Trigger: pushes and pull requests to `main` or `release/*` (ignores md files)
+    - Runs pytest on Python 3.12/3.13/3.14 with coverage and comments a summary
+
+- Code Quality Check (`code-quality-check.yml`)
+
+    - Trigger: pull requests
+    - Runs ruff and the rest of the pre-commit suite
+
+- Docs Deploy (`deploy.yml`)
+
+    - Trigger: push to `main` and tags `v*`
+    - Builds the `zensical` site and publishes to GitHub Pages
+    - Setup needed: enable GitHub Pages for the repo (Settings → Pages → Source: GitHub Actions)
+
+- Build and Release (`build_release.yml`)
+
+    - Trigger: tags `v*` push or manual workflow dispatch
+    - Builds a Windows x64 executable with PyInstaller, plus the wheel and sdist
+    - Publishes to PyPI (requires the `UV_PUBLISH_TOKEN` secret) and uploads every artifact to the GitHub Release
+
+- Publish Docker Image (`build_image.yml`)
+
+    - Trigger: push to `main` and tags `v*`
+    - Builds and pushes an image to GHCR: `ghcr.io/<owner>/<repo>`
+
+- Release Drafter (`release_drafter.yml`)
+
+    - Trigger: push to `main` and PR events
+    - Maintains a draft release based on Conventional Commits
+
+- Code Scanning (`code_scan.yml`)
+
+    - Trigger: push and PR
+    - Runs gitleaks; the CodeQL job needs GitHub Advanced Security and stays skipped while the repo is private
+
+- Semantic Pull Request (`semantic-pull-request.yml`)
+
+    - Trigger: PR open/edit/sync
+    - Enforces Conventional Commit style PR titles
+
+### CI/CD Configuration Checklist
+
+- Conventional commits for PR titles (enforced by the workflow)
+- Set the `UV_PUBLISH_TOKEN` secret to publish to PyPI (Settings → Secrets and variables → Actions)
+- Optional: enable GitHub Pages for docs deployment (Settings → Pages → Source: GitHub Actions)
+- Container Registry permissions are handled automatically via `GITHUB_TOKEN`
+
+## 🤝 Contributing
+
+- Open issues/PRs
+- Follow the coding style (ruff, type hints)
+- Use Conventional Commit messages and descriptive PR titles
+
+## 📄 License
+
+MIT — see `LICENSE`.