ok-script 2.0.17__tar.gz → 2.0.19__tar.gz

{ok_script-2.0.17 → ok_script-2.0.19}/.agents/skills/develop/SKILL.md

@@ -11,7 +11,15 @@ Do not use Computer Use skills, plugins, or tools for this workflow, including t
 
 Read [docs/mcp.md](../../../docs/mcp.md) for the current server, tools, task contract, and artifacts. The coding agent already has local file and process access: write code and read logs/images directly. Use [setup-env](../setup-env/SKILL.md) or [setup-project](../setup-project/SKILL.md) only when setup is missing.
 
-For screenshot annotations and named template features, use [generate-templates](../generate-templates/SKILL.md): retain originals and COCO annotations in `ok_templates`, export individual PNGs with `generate_templates` into `assets/templates`, and verify `find_feature`/`find_one` using the original feature names. Existing packed COCO assets and `coco_feature_json` remain supported. The split loader reports malformed filenames; fix the indicated asset instead of lowering matching thresholds or ignoring the error.
+Before creating or changing named image features, read [generate-templates](../generate-templates/SKILL.md) and use the library's authoring/export pipeline:
+
+1. Retain full original screenshots in `ok_templates/` and record feature rectangles and names in `ok_templates/coco_annotations.json` using `CocoTemplateStore`.
+2. Call `ok.feature.FeatureSet.generate_templates` to export split PNGs into `assets/templates/` (or `ok_tasks/assets/templates/` for custom scripts). Let the exporter write the geometry-bearing filenames.
+3. Configure `template_matching.template_folder` and use `find_feature`/`find_one` with the original feature names in task code.
+
+Do not replace this pipeline with hand-cropped runtime PNGs, a custom template registry, or a parallel `cv2.matchTemplate` loader for named features. Crop previews are diagnostics, not runtime assets. Existing packed COCO assets and `coco_feature_json` remain supported. The split loader reports malformed filenames; fix the source annotation and regenerate instead of renaming crops or ignoring the error.
+
+The full screenshots in `ok_templates/` can also serve directly as regression-test fixtures. Follow [write-test](../write-test/SKILL.md) to exercise real task recognition with `TaskTestCase.set_image()` or the exported assets with `FeatureSet`; there is no need to duplicate these images under `tests/images/`. A source-image self-match checks the export path; add independent positive and negative screenshots when available to check recognition robustness.
 
 For existing registered tasks, prefer [reload-tasks](../reload-tasks/SKILL.md): discover their source with `list_tasks()`, edit it in place, call `reload_tasks(task_ids=[...])`, and wait for a successful reload before testing. Keep automation behavior in its existing module; use temporary MCP files only as thin validation harnesses. Create new task implementations when the requested functionality is new.
 

{ok_script-2.0.17 → ok_script-2.0.19}/.agents/skills/generate-templates/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: generate-templates
-description: Create template matching assets for a third-party ok-script application from its screenshots and COCO annotations, then verify them with find_feature or find_one.
+description: Create or change named image features using ok-script's ok_templates screenshots, COCO annotations, and split exporter; verify them with find_feature or find_one and reuse screenshots in tests.
 ---
 
 # Generate and use templates
@@ -15,6 +15,13 @@ split runtime assets. Keep source screenshots intact so both agents and the
 Template tab can inspect and reannotate them. The old compression APIs and dialog
 option are obsolete; use the split exporter for new or regenerated assets.
 
+For new named features, do not write standalone runtime crops into `assets/`,
+invent a template metadata format, or implement a separate `cv2.matchTemplate`
+registry/loader. Use `CocoTemplateStore` for authoring, `generate_templates` for
+runtime exports, and the library's named-feature matching APIs in tasks. A crop
+preview may be written outside the export folder for inspection, but it does not
+replace the source screenshot, COCO annotation, or generated split asset.
+
 Run from the automation project's root using its interpreter, following
 [use-venv](../use_venv/SKILL.md). For live capture and task execution follow
 [develop](../develop/SKILL.md), including reset, baseline verification, and
@@ -172,6 +179,15 @@ prove recognition is robust. Use the project's actual threshold, preprocessing,
 and anchor settings for representative verification. Keep evidence of what was
 tested and what remains unverified.
 
+Full screenshots in `ok_templates/` are also reusable offline test fixtures.
+Pass their paths directly to `TaskTestCase.set_image()` to test the application's
+real recognition methods, or load them as frames for `FeatureSet` tests using
+the generated runtime assets. Keep referenced screenshots with the project so
+tests remain reproducible; copying them to `tests/images/` is unnecessary.
+Retain independent positive/negative captures when available, and assert the
+expected state or match geometry rather than only checking that an image loads.
+Follow [write-test](../write-test/SKILL.md) for harness setup and isolation.
+
 In task code, use the existing methods:
 
 ```python

ok_script-2.0.19/.agents/skills/setup-env/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: setup-env
+description: Install the ok-script Python package and create or repair a consuming application's virtual environment, including dependencies for its GUI or MCP server.
+---
+
+# Set Up the Local Environment
+
+Work in the consuming application's directory and use its configured environment or `.venv`. Inspect its requirements, lockfile, supported Python versions, and installed packages before changing dependencies. Installing and using ok-script does not require a library source checkout.
+
+Use this skill for requests such as "install ok-script and set up its environment", even before an MCP server exists. Read this file directly from the repository or installed package; starting MCP is not a prerequisite. After installation and verification, generate the local development skill before the project-creation handoff below.
+
+## Interpreter and dependencies
+
+- Resolve an existing `.venv\Scripts\python.exe` before any Python command. Use an absolute path when commands change directories. Use `-m pip`, `-m pytest`, and `-m py_compile` through that interpreter.
+- If a new environment is needed, create it with an available interpreter compatible with the application's requirements and its chosen ok-script release. Current releases require Windows and Python 3.11 or later. Inspect installed distribution metadata with `importlib.metadata` when needed. Do not recreate a working environment just to install missing packages.
+- Prefer the application's requirements or lockfile and preserve its chosen ok-script version. Select `default` for the normal vision/capture stack, `qt` for the desktop GUI, `adb` for Android targets, and `ocr` when required. A GUI application tested through MCP normally needs `default` and `qt`. MCP is a required dependency starting in ok-script 2.0.17; older pinned releases may still need their `mcp` extra. Install application test dependencies only when its tests need them.
+- OpenCV is deliberately separate from these profiles. Inspect the installed `opencv-*` packages and choose exactly one compatible variant. Reuse the project's existing choice when suitable; do not install multiple variants that all provide `cv2`.
+
+For an installed release, select the extras actually needed, for example:
+
+```powershell
+$projectPy = (Resolve-Path .\.venv\Scripts\python.exe).Path
+& $projectPy -m pip install 'ok-script[default,qt]'
+```
+
+Run this from the application's root. Install the chosen OpenCV variant separately if it is absent.
+
+Record the selected ok-script version or constraint, extras, and OpenCV variant in the application's existing dependency manifest or lockfile using its package manager. Keep setup reproducible without replacing unrelated dependencies.
+
+If the application intentionally uses an existing editable library installation or `ok` source link, preserve that arrangement and install its required dependencies in the application's environment. A source link alone does not install dependencies. Modify the application's tasks and configuration; library source changes are outside this skill's scope.
+
+Use the normal package index first. If downloads stall, a reachable alternate index can be supplied to the individual pip command; do not change persistent pip configuration as a side effect of setup.
+
+## Verify the environment
+
+Run `& $projectPy -m pip check`. Smoke-test `import ok, cv2, mcp` and the selected optional stacks, and verify `ok.__file__` resolves to the intended checkout or installed package. For Qt, check `from PySide6 import QtCore` and `import qfluentwidgets`.
+
+If the application already has a launcher, run it with its environment to catch runtime imports that dependency metadata alone cannot verify. Compile changed application scripts and run its existing tests when relevant.
+
+Report the environment path, dependency profiles, OpenCV choice, and verification outcome.
+
+## Generate the project-local development skill
+
+After successful installation, create
+`<cwd>/.agents/skills/ok-script-develop/SKILL.md` in the consuming workspace where
+the user requested setup. This is part of agent setup, including installation-only
+requests; it does not depend on accepting project creation or starting MCP. When
+repairing an environment, add the skill if it is missing.
+
+Use [the generic development skill template](assets/ok-script-develop/SKILL.md)
+as the initial content. Prefer the template shipped with the selected installed
+release; locate this `setup-env` skill through `ok.core.skills.list_skills()` and
+resolve `assets/ok-script-develop/SKILL.md` from its parent directory. If the
+installed release predates the template, use the template accompanying these
+setup instructions without upgrading the dependency.
+
+Create the destination directory as needed and write the template as UTF-8. If
+the destination already exists, read it first and preserve its project-specific
+guidance; merge missing discovery instructions only when needed. Do not replace
+a customized skill with the generic template. Keep the template's generic name
+and description for new skills; do not copy game-specific observations, fixed
+machine paths, or unrelated application skills from another project.
+
+The generated skill discovers the library's version-matched instructions in place;
+do not copy the full consumer skill catalog into the application. Verify the
+generated file has its `name` and `description` frontmatter, and that its discovery
+instructions locate this environment's `develop/SKILL.md`. Report the generated
+or reused skill's path with the environment results.
+
+## Offer to create a project
+
+After a successful initial installation, ask whether the user wants to create an automation project and which game or app it should target. For example: "ok-script is installed. Would you like to create an automation project now? If so, which game or app, and is it a Windows app or an Android device/emulator?" Wait for the answer before creating a project that has not already been requested.
+
+If project creation was already requested, continue with [setup-project](../setup-project/SKILL.md) and ask only for missing target/configuration details. That skill creates each project in its own subfolder with its own config and start scripts. Reuse the environment just prepared when compatible, adding any target-specific dependencies that become necessary.
+
+Do not repeat this offer when repairing an existing project's environment, returning to an ongoing `setup-project` workflow, or when the user has explicitly declined project creation. An installation request by itself should receive the offer; a running MCP server is not required for this conversation.

ok_script-2.0.19/.agents/skills/setup-env/assets/ok-script-develop/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: ok-script-develop
+description: Develop and debug an application's automation with ok-script, including tasks, configuration, recognition assets, and tests. Discover the selected library's consumer skills and apply the project's conventions.
+---
+
+# Develop with ok-script
+
+Work in the consuming application's project and use its configured Python
+environment. This skill provides discovery and project integration for any game
+or app using ok-script; the selected library supplies the development workflow
+and API contracts. Library maintenance is outside this skill's scope.
+
+## Locate the library instructions
+
+Before changing automation behavior, locate the consumer skills matching the
+library this application actually uses:
+
+1. Check the project's local `ok` directory or configured source link. Resolve
+   symlinks and junctions. A source checkout keeps skills at
+   `<resolved-ok>/../.agents/skills`; a packaged directory keeps them at
+   `<resolved-ok>/agent_resources/.agents/skills`.
+2. If that source has no consumer skills, use the application's interpreter and
+   `importlib.metadata.distribution('ok-script').locate_file('ok')` to locate its
+   installed package, then check `agent_resources/.agents/skills` there. Do not
+   use another environment's global installation.
+3. Read `develop/SKILL.md` in the selected skill directory. Resolve its links
+   relative to that original file, including the MCP guide and input references.
+   Read `reload-tasks` for registered tasks, `generate-templates` for visual
+   assets, and `write-test` for tests. Read setup skills when environment or
+   runtime setup is needed.
+
+When available, the selected package's `core/skills.py` provides `list_skills()`
+and `get_skill()` with absolute source paths. Load that file with
+`runpy.run_path` to discover instructions without importing the GUI runtime.
+For example, with a local `ok` directory, run this using the project interpreter
+from the application root:
+
+```python
+from pathlib import Path
+import runpy
+
+catalog = runpy.run_path(str(Path('ok').resolve() / 'core' / 'skills.py'))
+for skill in catalog['list_skills']():
+    print(skill['id'], skill['path'])
+```
+
+Keep the library's detailed instructions in their original location so they
+follow its installed version. Inspect that version's source and signatures for
+API details. If no consumer skills are available, report the missing resources
+and use the project's setup guidance; do not invent MCP tools or silently upgrade
+the dependency just to obtain instructions.
+
+## Apply the workflow to this project
+
+Follow the selected library's development skill for MCP startup, connection
+discovery, task recovery, reloads, and runtime validation. Use ok-script APIs and
+MCP for target capture and interaction. Do not use Computer Use skills, plugins,
+or tools for this workflow.
+
+Inspect the project's instructions, config, launchers, existing tasks, and local
+skills before implementing changes. Reuse its task bases, registration style,
+recovery helpers, assets, and localization conventions. Keep behavior in permanent
+application modules and use thin MCP harnesses to exercise those implementations.
+
+For new or changed named image features, read the library's `generate-templates`
+skill before creating assets. Keep full screenshots in `ok_templates/`, annotate
+them in `ok_templates/coco_annotations.json` with `CocoTemplateStore`, and call
+`generate_templates` to produce split features in `assets/templates/` (or
+`ok_tasks/assets/templates/` for custom scripts). Use the original names through
+`find_feature`/`find_one`. Do not substitute hand-cropped runtime PNGs, a custom
+template registry, or a separate `cv2.matchTemplate` loader for this pipeline.
+
+The full images in `ok_templates/` can also be used directly as regression-test
+fixtures with `TaskTestCase.set_image()` or `FeatureSet`. Read the library's
+`write-test` skill, exercise real recognition with generated assets, and retain
+independent positive/negative screenshots when available. The source-image
+self-match alone verifies export consistency, not recognition robustness.
+
+Use the configured project environment even when it is shared from a parent
+workspace. Reuse this project's live runtime when suitable and follow the
+library's process ownership rules when a restart is required. Validate observable
+target behavior and relevant GUI lifecycle paths as described by the library.
+If the target is unavailable, continue useful code and offline checks and report
+the specific runtime checks that remain unverified.

ok_script-2.0.19/.agents/skills/setup-project/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: setup-project
+description: Create or configure an ok-script automation project, collect missing game or app details, and give each project its own subfolder, config, GUI and MCP start scripts, and Windows shortcut.
+---
+
+# Set Up a Local Automation Project
+
+Work in the consuming application's directory at the user's requested location. Inspect an existing project before adding files. Use [setup-env](../setup-env/SKILL.md) when its environment needs preparation, and [docs/mcp.md](../../../docs/mcp.md) for current CLI and server configuration. Configure the application through the installed library's APIs; no ok-script source checkout is required.
+
+## Collect the target details
+
+When following an installation-only request, first ask whether the user wants a project, as described in `setup-env`. If they already requested a project, proceed without asking for the same confirmation again. Reuse details from the request and existing project, and ask a short grouped question for missing information:
+
+- Which game or app should this project automate, and is it a Windows application or an Android device/emulator?
+- For Windows, which installed executable or running window is the target? Inspect running processes and windows when possible; ask for the executable path or window choice when the target cannot be identified unambiguously. Determine whether the launcher should open the target or attach to an already-running instance. Automatic startup requires its actual launch path or command.
+- For Android, which device or emulator and which app should be targeted? Inspect available devices and the installed library's configuration before asking for identifiers the agent can discover itself. Ask the user to choose when multiple targets match.
+
+Use a sensible project folder name derived from the app unless the user supplies one. Use the current workspace as the parent unless another location was requested. Ask about additional requirements, such as background operation, only when they affect the requested setup. Select and verify capture/input backends using the installed APIs; the user need not know their technical names.
+
+Wait for essential target details before writing target-dependent configuration. Do not use example executable names or window titles as if they were verified. If environment setup is still needed, it can proceed while the target question is pending.
+
+## Layout and source access
+
+Create each new automation project in its own named subfolder under the workspace. Each project must have its own `config.py`, `start_gui.py`, and `start_mcp.py` inside that subfolder. Keep its task modules, assets, mutable configuration, logs, and screenshots there too. For example:
+
+```text
+workspace/
+  .venv/
+  my-game/
+    config.py
+    start_gui.py
+    start_mcp.py
+    tasks/
+    assets/
+    configs/
+    logs/
+    screenshots/
+  another-app/
+    config.py
+    start_gui.py
+    start_mcp.py
+```
+
+Create supporting directories as needed. Reuse a matching existing project folder; if the current directory is already that project's folder, edit it in place rather than nesting another copy. Keep separate projects' config and launch scripts separate, even when they target the same app.
+
+Ensure each application's root has `.agents/skills/ok-script-develop/SKILL.md`,
+following the local skill generation instructions in [setup-env](../setup-env/SKILL.md).
+Do this even when its environment is shared with the parent workspace, so an agent
+opened directly in the application folder can discover development guidance.
+Preserve existing project-specific skill content.
+
+Projects may share the workspace environment just installed when their dependencies are compatible, or use a project-local environment when required. Record the chosen interpreter and use its absolute path in shortcuts and run instructions. Target launchers must work when invoked by absolute path from another working directory: resolve paths from `__file__`, make the project's task modules and config importable, and set the working directory to that project's subfolder before starting the runtime. Resolve mutable paths under that same folder so projects do not share settings, logs, or MCP ownership accidentally.
+
+Prefer the application's installed ok-script dependency. If the user explicitly requests a source link to an existing library installation, link `<project-root>\ok` to that checkout's `ok` directory and add the link's parent to `sys.path` before importing `ok`. Prefer a directory symbolic link; if Windows denies symlink privileges, use a directory junction. Verify existing destinations and resolved paths before replacing anything; never recursively delete through the link. This is dependency access, not permission to modify library code.
+
+When obtaining a requested test application, record its source and checksum, verify the file type, and preserve existing downloads. Reuse an existing process only when its resolved executable path matches the intended target.
+
+## Application config
+
+Build a project-local config using the actual target's executable, title, capture backend, and interaction backend. Resolve mutable paths under the target folder. A Windows GUI project commonly has:
+
+```python
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent
+config = {
+    'version': '0.1.0',
+    'gui_title': 'Automation Playground',
+    'gui': {'type': 'qt'},
+    'debug': False,
+    'config_folder': str(ROOT / 'configs'),
+    'screenshots_folder': str(ROOT / 'screenshots'),
+    'windows': {
+        'exe': ['target.exe'],
+        'title': 'Target Window',
+        'capture_method': ['BitBlt'],
+        'interaction': 'PostMessage',
+        'start_exe': True,
+        'calculate_pc_exe_path': str(ROOT / 'target.exe'),
+    },
+    'onetime_tasks': [],
+    'trigger_tasks': [],
+    'mcp': {
+        'enabled': False,
+        'port': 8765,
+        'artifact_directory': str(ROOT / 'logs' / 'mcp'),
+    },
+}
+```
+
+Adapt this example. BitBlt and PostMessage are initial candidates, not proof of target compatibility. Register a completed task as `['task_module', 'Task']` in `onetime_tasks`, using an import path available to both launchers.
+
+If the task needs named template matching, add `template_matching` with
+`'template_folder': str(ROOT / 'assets' / 'templates')` and the project's matching
+settings. Keep an existing `coco_feature_json` entry when packed assets are still
+used; both sources can coexist. Keep editable screenshots and COCO annotations
+under `ok_templates`, separate from exported crops. Follow
+[generate-templates](../generate-templates/SKILL.md) for export and verification.
+
+## Separate launchers
+
+- `start_gui.py` is the user entry point. Explicitly select the Qt GUI and disable MCP. Launch it with the project's `pythonw.exe`. Redirect absent stdout/stderr to a local startup log so startup errors remain observable without a console.
+- `start_mcp.py` is the coding agent entry point. Enable MCP and normally run headless; support a configurable port when useful. If GUI-assisted development is needed, keep that entry point separate from the user launcher. The agent can start the process itself; do not require the user to open a console.
+- Keep both scripts in the project's subfolder and load that project's `config.py`. Share path setup and target process startup in a project-local launcher helper when useful. Copy config before applying mode-specific overrides. Clean up the runtime on exit.
+- A user `.lnk` targets the absolute venv `pythonw.exe`, passes a quoted absolute `start_gui.py` path, and sets the working directory. Use a custom shortcut icon when one is supplied. A hidden `python.exe` console does not replace `pythonw.exe` for the user shortcut.
+
+Starting a GUI replaces the registered console owner for the same working directory, closing that console's MCP server. Keep both launchers in the same target directory so project ownership matches. Close the GUI before starting a console development session. Never kill arbitrary Python processes to free a port; identify the owning project and PID.
+
+## Verify against the real target
+
+Start the development launcher and inspect an MCP screenshot for a complete, current target image. Test reset, left/right clicks, keys, or other required input against observable UI changes. Prioritize PostMessage, checking background operation while the target is unfocused or covered and confirming that foreground focus and the cursor remain undisturbed. Do not infer minimized-window support from those checks.
+
+If capture is cropped or stale, inspect backend behavior and DPI/coordinate scaling before changing recognition code. For a legacy application, a child-only `HIGHDPIAWARE` compatibility environment may help; apply it only when verified, rather than globally changing Windows settings.
+
+Launch the actual user shortcut: confirm the GUI opens without a console or MCP listener and loads this project's config. When a task was also requested and implemented, confirm it appears with a useful name and its Start action runs successfully; see [develop](../develop/SKILL.md) for task lifecycle and retry behavior. A new project without tasks should still open successfully. Report the project folder, config, selected interpreter, concrete launcher paths, and the interaction/capture behavior that was tested.

{ok_script-2.0.17 → ok_script-2.0.19}/.agents/skills/write-test/SKILL.md

@@ -27,7 +27,7 @@ Import `TaskTestCase` from `ok.test.TaskTestCase`; set class attributes `task_cl
 
 The current harness initializes one task per test class, replaces capture with `ImageCaptureMethod`, and uses `DoNothingInteraction`. `set_image(path)` advances the frame and checks template sizing; `set_images(*paths)` installs a sequence and advances its first frame. Read the capture implementation when testing frame progression rather than assuming repeated reads advance it.
 
-- Store reproducible screenshots under the target project's `tests/images/`, or reuse an existing tracked `ok_templates` source when appropriate. Confirm each fixture exists and loads.
+- Reuse full source screenshots in the target project's `ok_templates/` directly as test fixtures, including screenshots used to author COCO annotations and split features. Pass their paths to `set_image()`; no copy into `tests/images/` is required. Keep referenced images with the project and confirm they exist and load. Additional test-only captures may live under `tests/images/` or the project's existing fixture directory.
 - Load the image before calling the recognition method. Exercise real recognition rather than mocking the method being tested.
 - Assert the detected state, value, feature name, confidence, or box geometry as appropriate. Include an absent or negative case when it distinguishes the regression.
 - For scaling bugs, use representative resolutions and aspect ratios with `subTest`; preserve the intended center/right anchors and allow a justified pixel tolerance. Include positive matches and blank-frame negatives when relevant.
@@ -35,6 +35,15 @@ The current harness initializes one task per test class, replaces capture with `
 - Do not treat no-op input as proof that an in-game click worked. Test action intent with mocks; use the [develop skill](../develop/SKILL.md) when actual GUI/MCP interaction is part of the request.
 - For fixture annotation or named feature creation, follow [generate-templates](../generate-templates/SKILL.md).
 
+For example, in a `TaskTestCase` method, call
+`self.set_image(str(project_root / "ok_templates" / "settings-open.png"))`, then
+invoke the real task recognition method and assert its result. Resolve
+`project_root` from the test file or the project's existing test configuration.
+Use the generated `assets/templates` features through the real application
+config. Matching a feature against its own authoring screenshot verifies the
+annotation/export/load path; include independent positives and negatives when
+available to catch false matches and appearance changes.
+
 For direct split-template tests, construct `FeatureSet(False, None, 0.002, 0.002,
 template_folder=<absolute export folder>)`. For packed COCO tests, pass the JSON
 path as the second argument. Match using the original feature name, without the

{ok_script-2.0.17 → ok_script-2.0.19}/MANIFEST.in

@@ -1,6 +1,7 @@
 recursive-include ok *
 recursive-include .agents/skills *
 include docs/mcp.md
+include docs/agent-setup.md
 include docs/feature-crops.md
 include examples/mcp_observe.py
 global-exclude *.pyc

{ok_script-2.0.17 → ok_script-2.0.19}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ok-script
-Version: 2.0.17
+Version: 2.0.19
 Summary: Automation with Computer Vision for Python
 Author-email: ok-oldking <firedcto@gmail.com>
 License: ok-script License
@@ -79,6 +79,7 @@ License: ok-script License
         
 Project-URL: Homepage, https://github.com/ok-oldking/ok-script
 Project-URL: Repository, https://github.com/ok-oldking/ok-script
+Project-URL: Agent setup, https://github.com/ok-oldking/ok-script/blob/master/docs/agent-setup.md
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
@@ -140,6 +141,14 @@ ok-script 支持 Windows 应用和游戏、安卓模拟器及 ADB 设备，提
 
 ## 可以这样告诉编程代理
 
+首次安装环境：
+
+> 在当前项目中安装 ok-script 并配置运行环境。先读取 https://raw.githubusercontent.com/ok-oldking/ok-script/master/docs/agent-setup.md ，按照其中的安装技能操作，保留项目现有的依赖约束。
+
+[代理安装指南（英文）](docs/agent-setup.md)提供可添加到应用项目 `AGENTS.md` 的简短指令，让后续安装请求也能找到这些技能，无需先安装包或启动 MCP。
+
+开发自动化任务：
+
 > 连接这个项目的 ok-script MCP 服务，读取开发技能。检查已安装的截图、匹配和输入 API，给出准确签名和源码位置。开发可复用 Python 任务：打开设置、启用“显示详情”、保存并验证结果。每次尝试前恢复并验证起始界面，测试重复运行，代码保存到项目中。使用 ok-script API 和 MCP，不使用 Computer Use 工具。最后给出不依赖代理或大模型调用的准确运行命令。
 
 ## 特性

{ok_script-2.0.17 → ok_script-2.0.19}/README.md

@@ -14,6 +14,14 @@ ok-script 支持 Windows 应用和游戏、安卓模拟器及 ADB 设备，提
 
 ## 可以这样告诉编程代理
 
+首次安装环境：
+
+> 在当前项目中安装 ok-script 并配置运行环境。先读取 https://raw.githubusercontent.com/ok-oldking/ok-script/master/docs/agent-setup.md ，按照其中的安装技能操作，保留项目现有的依赖约束。
+
+[代理安装指南（英文）](docs/agent-setup.md)提供可添加到应用项目 `AGENTS.md` 的简短指令，让后续安装请求也能找到这些技能，无需先安装包或启动 MCP。
+
+开发自动化任务：
+
 > 连接这个项目的 ok-script MCP 服务，读取开发技能。检查已安装的截图、匹配和输入 API，给出准确签名和源码位置。开发可复用 Python 任务：打开设置、启用“显示详情”、保存并验证结果。每次尝试前恢复并验证起始界面，测试重复运行，代码保存到项目中。使用 ok-script API 和 MCP，不使用 Computer Use 工具。最后给出不依赖代理或大模型调用的准确运行命令。
 
 ## 特性

ok_script-2.0.19/docs/agent-setup.md

@@ -0,0 +1,108 @@
+# Set up ok-script with a coding agent
+
+Use this entry point when asked to install the `ok-script` Python package, prepare
+its environment, or set up an automation project that uses it. Work in the
+consuming application's folder. The library source does not need to be cloned.
+
+## Give the agent an entry point
+
+For a one-time setup, tell your coding agent:
+
+> Install ok-script and set up this project's environment. First read https://raw.githubusercontent.com/ok-oldking/ok-script/master/docs/agent-setup.md and follow the relevant setup skills linked there. Preserve this project's existing dependency constraints.
+
+For future requests such as "install ok-script and set up its environment", add
+the following to the consuming project's `AGENTS.md`, or the instruction file
+your coding agent reads:
+
+```markdown
+## ok-script setup
+
+When asked to install, configure, or repair ok-script or its Python environment,
+read https://raw.githubusercontent.com/ok-oldking/ok-script/master/docs/agent-setup.md
+and follow the relevant setup skills before changing the environment.
+Use this project's virtual environment and preserve its dependency constraints.
+After installation, generate .agents/skills/ok-script-develop/SKILL.md in the
+current workspace using the setup-env template, preserving any existing custom skill.
+After installation, offer to create an automation project and ask for missing
+game/app details. Give each project its own subfolder, config, and start scripts.
+```
+
+Installing a Python package does not register its instructions with a coding
+agent. The prompt or project instruction supplies the discovery link; after
+installation, the package also provides local copies of the skills. The coding
+agent then generates a discoverable development skill in the consuming workspace;
+`pip install` alone does not write project instructions. No MCP server is needed
+to read the setup instructions or generate this local skill.
+
+## Instructions for the coding agent
+
+1. Inspect the consuming project's instructions, Python requirements, lockfile,
+   existing environment, and requested outcome. This is application setup, not
+   development of the ok-script library. For a new environment, ok-script
+   currently requires Windows and Python 3.11 or later; check the selected
+   release's package metadata for its requirements.
+2. Read the
+   [setup-env skill](https://github.com/ok-oldking/ok-script/blob/master/.agents/skills/setup-env/SKILL.md)
+   before installing or repairing dependencies. It covers environment creation,
+   optional dependency profiles, the separate OpenCV choice, and verification.
+   If reading remotely, resolve that skill's relative links against its location
+   in this repository. Preserve existing pins and use instructions from the
+   matching release or local package when available.
+3. Install in the application's environment and record the chosen dependencies
+   in its existing dependency manifest or lockfile. Follow its package manager's
+   workflow. Select only the profiles the requested application needs; a desktop
+   GUI commonly uses `default,qt`, with exactly one compatible OpenCV variant
+   installed separately. Verify the environment before offering project creation.
+4. After installation, generate
+   `<cwd>/.agents/skills/ok-script-develop/SKILL.md` using the generic template
+   linked from `setup-env`. This step also applies to installation-only requests;
+   preserve and merge an existing customized skill rather than overwriting it.
+   Verify it can locate the selected library's consumer development instructions.
+   The skill applies to any consuming game or app and discovers the library's
+   instructions in place instead of duplicating them.
+5. After a successful initial installation, ask: "Would you like to create an
+   automation project now? Which game or app should it automate, and is it a
+   Windows app or an Android device/emulator?" If the user already requested a
+   project, ask only for missing details. Skip this offer when repairing an
+   existing project or when the user has explicitly declined project creation.
+6. When project creation is requested, read the
+   [setup-project skill](https://github.com/ok-oldking/ok-script/blob/master/.agents/skills/setup-project/SKILL.md).
+   Identify the actual executable/window or device/app from the user's answers
+   and local inspection. Ask for any required details that remain ambiguous;
+   wait for those answers before writing target-dependent config. Create each
+   project in its own named workspace subfolder, containing its own `config.py`,
+   `start_gui.py`, and `start_mcp.py`. Keep its tasks, assets, settings, and logs
+   in that folder too. Ensure its root also has the local `ok-script-develop`
+   skill, even if it shares the workspace environment. Omit `gui_icon` to use the
+   default `OK` PNG bundled with
+   the Python package; set it only when supplying a custom application icon.
+   Reuse an existing project in place. Projects may share
+   the prepared environment when compatible. Use the installed version's APIs
+   and verify that launchers work when invoked from outside their subfolder.
+7. Run the checks in the relevant skills. Report the environment path, installed
+   ok-script version, dependency profiles, OpenCV choice, and verification
+   results, plus the generated or reused development skill path. For application
+   setup, also report the project folder, config,
+   launcher paths, and which target capture/input checks succeeded.
+
+## Read skills from an installed package
+
+Use the selected environment's interpreter to obtain skill metadata and absolute
+source paths without starting the GUI or MCP server. This example runs from the
+workspace containing `.venv`; a project subfolder can use that same interpreter
+by its resolved absolute path:
+
+```powershell
+$projectPy = (Resolve-Path .\.venv\Scripts\python.exe).Path
+& $projectPy -c "from ok.core.skills import list_skills; import json; print(json.dumps(list_skills(), indent=2))"
+```
+
+Read the returned `setup-env` or `setup-project` path and resolve relative links
+from that file. These local copies match the installed package. If an older
+release does not include skills, use this repository's instructions and inspect
+the installed APIs rather than upgrading just to obtain instructions.
+
+Once a requested MCP runtime is running, `list_skills()` and
+`get_skill("setup-project")` expose the same instructions. See the
+[MCP guide](mcp.md) for connection details and the
+[development prompts](en/agent-prompts.md) for subsequent task implementation.

{ok_script-2.0.17 → ok_script-2.0.19}/docs/feature-crops.md

@@ -14,6 +14,11 @@ Use Split for new exports. Existing COCO assets remain readable.
 Keep the original screenshots and COCO annotations in `ok_templates` for editing
 and future exports. Split exports require only the PNG files at runtime.
 
+Coding agents should use this same pipeline: author with `CocoTemplateStore`,
+export with `generate_templates`, and match named features with
+`find_feature`/`find_one`. Hand-cropped runtime PNGs and a custom OpenCV template
+loader bypass the library's annotation, scaling, and export workflow.
+
 ## Configuration
 
 Add `template_folder` alongside the existing configuration; all variance,
@@ -106,6 +111,14 @@ boxes = features.find_feature(frame, 'settings_save', threshold=0.95)
 assert len(boxes) == 1, boxes
 ```
 
+Full screenshots in `ok_templates` can also serve directly as regression-test
+fixtures. Pass a screenshot path to `TaskTestCase.set_image()` to exercise the
+application's real recognition methods, or load it for a `FeatureSet` test as
+above. Keep referenced screenshots with the project; no duplicate under
+`tests/images` is needed. A self-match on the authoring image verifies the export
+path. Add independent positive and negative screenshots when available to test
+recognition robustness, using the application's actual matching settings.
+
 Also verify representative screenshots at the supported resolutions. The GUI
 Save action reloads its feature set. After programmatic export, refresh cached
 features with `feature_set.process_data()` on the executor thread, or restart the

{ok_script-2.0.17 → ok_script-2.0.19}/docs/mcp.md

@@ -12,8 +12,19 @@ The agent writes and edits project files, starts the local runtime, and reads lo
 
 MCP supplies skills and task execution, not a Python API catalog or `get_api` tool. Use the application's interpreter and inspect its installed package for exact signatures, docstrings, inherited methods, and return behavior. No library checkout is needed. See [agent prompts](en/agent-prompts.md) for API-only discovery and existing-task repair examples.
 
+The server's connection instructions direct agents to `get_skill("generate-templates")`
+before creating named image features: keep full screenshots and COCO annotations
+in `ok_templates`, export split features with `generate_templates`, and use
+`find_feature`/`find_one` in tasks. Those full screenshots can also be used directly
+as regression-test fixtures; `get_skill("write-test")` describes the test workflow.
+These instructions and skills come from the server's installed ok-script version.
+
 ## Install and start
 
+If the project has no environment or MCP runtime yet, start with the
+[agent setup guide](agent-setup.md). Its setup skills can be read before
+installation, without connecting to a running server.
+
 MCP is a required dependency of ok-script starting in 2.0.17. Install the capture
 and OCR profiles your project needs; no separate MCP extra is required.
 Use the project's virtual environment when one exists:

{ok_script-2.0.17 → ok_script-2.0.19}/ok/__init__.py

@@ -14,7 +14,7 @@ from typing import TYPE_CHECKING
 from ok.util.handler import Handler, ExitEvent
 from ok.util.logger import Logger
 from ok.util.file import get_path_relative_to_exe
-from ok.core.ui_config import resolve_ui_config, resolve_window_size
+from ok.core.ui_config import resolve_gui_icon, resolve_ui_config, resolve_window_size
 os.environ["PYTHONIOENCODING"] = "utf-8"
 
 if TYPE_CHECKING:
@@ -333,7 +333,7 @@ class App(_OverlayConfigMixin):
         self.overlay_window = None
         self.main_window = None
         self.exit_event = exit_event
-        self.icon = QIcon(get_path_relative_to_exe(config.get('gui_icon')) or ":/icon/icon.ico")
+        self.icon = QIcon(get_path_relative_to_exe(resolve_gui_icon(config)))
 
         from ok.core.start_controller import StartController
         self.start_controller = StartController(self.config, exit_event)
@@ -654,6 +654,7 @@ class OK:
         import pyappify
         from ok.util.config import Config
 
+        config['gui_icon'] = resolve_gui_icon(config)
         self.config = config
         check_mutex_fn = _resolve('check_mutex')
         config_logger_fn = _resolve('config_logger')