detain

Scaffolds a new SugarCraft monorepo port end-to-end across every touchpoint: creates <slug>/composer.json + phpunit.xml + README.md + CALIBER_LEARNINGS.md + src/<Class>.php, then wires it into root composer.json (require + repositories[]), docs/MATCHUPS.md, PROJECT_NAMES.md, root README.md table, docs/index.html tiles, docs/_data/<slug>.{json,body.html} → tools/gen-docs.php, media/icons/<slug>.png, .github/workflows/vhs.yml matrix, and codecov.yml (flag + component). Use when the user says 'add a library', 'port <upstream>', 'scaffold lib <slug>', 'new candy-/sugar-/honey- lib', 'create SugarX'. Do NOT use to edit an existing lib's metadata (use direct Edit), add a feature to an existing lib (follow that lib's CALIBER_LEARNINGS.md), rename a lib, or add a plain sugarcraft dep to an existing lib (use path-repo-closure).

Adds a translation file at `<slug>/lang/<code>.php` by copying the library's `en.php` and translating only the values while preserving every array key and `{placeholder}` token verbatim; locale codes come from `LOCALES.md`. Use when the user says 'add <language> translation', 'translate <lib> to <code>', 'add Japanese/French/etc. locale', or 'add es.php to sugar-charts'. Do NOT use to edit `en.php` (it is the source of truth), to first-time-wire `Lang::t()` into a lib that has no `lang/` directory yet, or to change the base `SugarCraft\Core\I18n\Lang`/`T` machinery.

Propagates a new sugarcraft/<dep> dependency across every consuming composer.json — adds the require entry plus a {type:path, url:"../<dep>", options:{symlink:true}} repository for the FULL transitive closure (mirrors sugar-charts/composer.json), then verifies with tools/check-path-repos.php. Use when the user says 'add dep on <slug>', 'wire up <slug>', 'new transitive dep', or edits a require["sugarcraft/..."] line. Do NOT use for non-sugarcraft Packagist deps (those need only a require bump, no path-repo) or for scaffolding a whole new library (use scaffold-library / add-library-checklist).

Scaffolds a new immutable+fluent SugarCraft class — `final`, `declare(strict_types=1)`, a private constructor with public `readonly` promoted props, `::new()` factory, `with*()` setters that return a new instance, bare accessors (no `get`), and (for TUI roots) the candy-core `Model` contract `init()`/`update(Msg): [Model, ?Cmd]`/`view()`/`subscriptions()`. Mirror `candy-sprinkles/src/Style.php` (value object) or `sugar-bits/src/Stopwatch/Stopwatch.php` (Model). Use when the user says 'add a Model', 'new TUI widget', 'scaffold a SugarCraft class', 'port from charmbracelet/<x>', or creates files under `<slug>/src/`. Do NOT use for editing an existing class (use direct Edit), tests-only changes (use write-phpunit-test), scaffolding a whole new library skeleton (use scaffold-library), or non-SugarCraft repos.

Writes PHPUnit 10 tests for SugarCraft TEA libs in the four project modes — snapshot byte (view()→raw SGR), cell-grid (SugarCraft\Vt\Terminal / Buffer), behaviour (update()→[Model,?Cmd]), and coercion (clamp/throw edges) — plus golden-file and program-driving helpers from candy-testing (Assertions::assertGoldenAnsi/assertCellGrid/assertViewIdempotent, ProgramSimulator, ScriptedInput). Use when the user says 'write a test', 'add snapshot test', 'add golden test', 'test this Model', 'test update()', or 'test view() output' for any candy-*/sugar-*/honey-* lib. Do NOT use to duplicate a canonical lib's suite into a class_alias façade lib (ship a single AliasesTest asserting each alias resolves to its canonical FQN instead), and do NOT use for non-TUI plain-PHP unit tests that have no view()/update()/Model.

Processes docs/plans/AUDIT_*.md files by marking items ✅/⏭️ inline where they live (never moving them — readers see history in place), skipping 'credit upstream author' and UPGRADE_GUIDE items (out of scope pre-1.0), and splitting multi-lib audits into one PR per lib sequenced by dependency order (candy-core → candy-sprinkles → honey-bounce → leaf libs). Use when the user says 'work through audit', 'process AUDIT_*.md', 'fix audit findings', or names a docs/plans/AUDIT_*.md file. Do NOT bundle multiple libs into one PR, do NOT use for net-new feature work, and do NOT retroactively rewrite or force-push already-merged audit PRs.

Scaffolds a new SugarCraft library end-to-end per the AGENTS.md checklist. Creates <slug>/composer.json (path-repo closure copied from sugar-charts), README.md, CALIBER_LEARNINGS.md, phpunit.xml, src/<Class>.php with declare(strict_types=1) + PSR-4 namespace, tests/ stub, and updates root composer.json + MATCHUPS.md + PROJECT_NAMES.md + README.md table + docs/index.html tile + docs/lib/<slug>.html + .github/workflows/ci.yml + .github/workflows/vhs.yml + codecov.yml. Use when user says 'add new library', 'port <upstream>', 'create candy-X', 'create sugar-Y', or 'create honey-Z'. Do NOT use for adding features to an existing lib (follow that lib's CALIBER_LEARNINGS.md instead) or for renaming libs (separate flow).

Creates a VHS .tape file at <slug>/.vhs/<demo>.tape driving php examples/<demo>.php with TokyoNight theme and the standard FontSize/Width/Height/Type/Enter/Sleep sequence. Also adds the lib to the hand-maintained matrix in .github/workflows/vhs.yml when missing. Use when user says 'add VHS demo', 'record gif', 'new tape file', 'add a tape for <slug>'. Do NOT use for editing an existing tape's visual style, rendering GIFs locally (CI does that via vhs.yml), or for non-visual libs (candy-pty, FFI/syscall wrappers) — those are exempt from the .vhs/ + matrix requirement.

Scaffolds a new affiliate-system page under src/views/billing/affiliates/ following patterns in Affiliate.vue, Faq.vue, RichReport.vue, SalesGraph.vue, etc. Wires the route as a child of /affiliate in src/router/index.ts with meta.i18n: ['affiliate'] and adds keys under src/locales/en/affiliate.json. Use when user says 'add affiliate page', 'new affiliate report', 'affiliate dashboard view'. Do NOT use for non-affiliate billing pages (Cart, Invoices, PrePays) — those live directly under src/views/billing/.

Adds an MSW request handler to src/mocks/handlers.ts for new API endpoints exercised by Vitest/jsdom tests, with optional parallel entry in test/visual/mocks/visualHandlers.ts for visual regression coverage. Follows the project's exact pattern: http.get/post against BASE_URL='https://my.interserver.net/apiv2', returns HttpResponse.json() with realistic shapes that match fetchWrapper consumers. Use when user says 'add msw handler', 'mock this endpoint', 'add API mock', 'stub this API for tests', or implements a new fetchWrapper call that has no existing mock. Do NOT use for editing existing handlers, for Playwright e2e/ tests (those hit the dev server), for e2e/real/ tests (real backend), or for service worker patches in public/mockServiceWorker.js.

Scaffolds a new sub-action child component for VPS/QS/server/website services (e.g., src/views/vps/ChangeTimezone.vue, src/views/quickservers/Backup.vue). Sub-actions are rendered inside View{Service}.vue when route.params.link matches the action name in the :link(...) enum in src/router/index.ts. Uses fetchWrapper, Swal confirmations, useI18n() with the parent namespace, and follows the structure of existing sub-actions like src/views/vps/ResetPassword.vue or src/views/vps/ChangeTimezone.vue. Use when user says 'add sub-action', 'new VPS action', 'add ChangeX page', 'register new :link action'. Do NOT use for top-level list/view/order pages (use add-service-list/add-service-view/add-route).

Creates a new i18n locale namespace JSON file in src/locales/en/{namespace}.json with properly structured translation keys, then propagates to other language directories. Use when user says 'add translations', 'new locale file', 'add i18n namespace', or creates a new view domain that needs translations. Do NOT use for editing existing locale files or fixing individual translation keys.

Creates a new Pinia store in src/stores/{domain}.store.ts following the Options API pattern with fetchWrapper, typed state interfaces, and standard CRUD actions. Use when user says 'add store', 'create new store', 'new Pinia store for {domain}'. Do NOT use for modifying existing stores or for non-service stores like auth/alert.

Adds new route entries to src/router/index.ts following the project's nested route pattern with lazy-loaded components, meta.i18n namespaces, parameterized :id(\d+) paths, and :link(action1|action2) sub-routes. Use when user says 'add route', 'new page route', 'register route for new service'. Do NOT use for redirect-only routes.

Creates a new service list page using the ServiceListTable component from src/components/ServiceListTable.vue. Follows the pattern in src/views/webhosting/WebsitesList.vue — defines columns, fetches data via fetchWrapper, sets breadcrumbs via useSiteStore. Use when user says 'add list page', 'create services list', 'new {service} list view'. Do NOT use for detail/view pages or order pages.

Creates a new shared Vue component in src/components/ following the project's Composition API pattern with <script setup lang='ts'>, useI18n(), and Admin-LTE/Bootstrap 4 markup. Handles props typing, emits, and fetchWrapper integration. Use when user says 'add component', 'create shared component', 'new reusable widget'. Do NOT use for view pages (use add-service-view/add-service-list) or store files.

Creates a new ORM/DB-aware symbol pack under profiles/db-aware-<name>.json plus the matching ProjectProfileDetector::detectIn() composer-package marker and KNOWN_PROFILES entry, threading it through tests/Unit/Cli/ProjectProfileDetectorTest.php. Use when user says 'add db-aware profile for <orm>', 'support <orm> in --db-aware', 'add symbol pack', 'extend DbOpRegistry for <library>', or adds a file to profiles/db-aware-*.json. Capabilities: enforce lower-cased method keys, validate values against db.read|db.write|db.delete|db.execute|db.query, pick the right composer-package signal (require + require-dev), register in KNOWN_PROFILES in correct order, cover detection in ProjectProfileDetectorTest. Do NOT use for framework auto-tune profiles (laravel/symfony/drupal/wordpress — those live at profiles/<framework>.json and tune excludes/min_block_size, not db_symbols), do NOT use to edit existing db-aware packs (just modify the JSON in-place), do NOT use for renaming/removing an existing pack.

Build terminal UIs with Charmbracelet (Bubble Tea, Lip Gloss, Gum). Use when: Go TUI, shell prompts/spinners, "make CLI prettier", adaptive layouts, async rendering, focus state machines, sparklines, heatmaps, kanban boards, SSH apps.

Adds a new CLI flag in src/Cli/Command.php::configure() and threads it through ConfigLoader (load + validate + shapeOverrides), Config constructor (with range check), docs/config-schema.json, docs/CLI.md, and ConfigLoaderTest. Use when the user says 'add flag', 'new CLI option', 'add --<name>', or 'expose <config> on the command line'. Enforces the kebab-case CLI / snake_case override-key / camelCase Config-property naming convention and the four flag groups (Detection tuning, Output/reports, Performance/runtime, Interactive/UI). Do NOT use for renaming an existing flag (breaking change — propose an alias instead) or for adding a new subcommand (different scaffold under SymfonyCommand).

Adds a new cooperative stage in src/Pipeline/Stages/ following ScanningStage/PreprocessStage patterns: StageInterface vs CooperativeStageInterface choice, YIELD_EVERY constant, ProgressListener wiring with NullProgressListener fallback, PipelineState field additions, and threading into Command::execute()'s $buildPipeline closure in canonical Scanning→Preprocess→Cluster→Refactor→Report order. Use when user says 'add pipeline stage', 'new pipeline phase', 'extend the pipeline', or 'add a stage between X and Y'. Do NOT use for modifying existing stages (edit them in place), adding reporters (use add-reporter), or adding new Clusterer sub-phases (those go inside ClusterStage::iter()).

Adds a new output format under src/Reporting/ as a final class with writeTo(Report, string): void plus a pure build(Report) helper, then wires it through src/Pipeline/Stages/ReportStage.php and adds a matching --<name> flag in src/Cli/Command.php (with grouped-help entry and $reportArgs threading). Use when the user says 'add reporter', 'new output format', 'export to <format>' (e.g. junit, ndjson, yaml, xml), or when adding a file to src/Reporting/. Capabilities: scaffolding the final reporter class, registering ReportStage constructor + run() emit, adding the CLI flag, threading $reportArgs, and creating tests/Unit/Reporting/<Name>ReporterTest.php with a synthetic Report. Do NOT use for CliReporter verbosity tweaks (those go through --summary-only / --clusters / VERBOSITY_* constants), HTML/CSS-only changes inside HtmlReporter, new cluster sort keys (see src/Reporting/ClusterSort.php), or analyzers under src/Reporting/Coherence*/Architecture analyzers.

Adds a new CLI flag in src/Cli/Command.php::configure() and threads it through ConfigLoader, Config, docs/config-schema.json, and docs/CLI.md. Use when the user says 'add flag', 'new CLI option', 'add --<name>', or 'expose <config> on the command line'. Covers the four flag groups (Detection tuning, Output/reports, Performance/runtime, Interactive/UI), default-handling, validation/exit-2 patterns, profile-key mapping, and ConfigLoaderTest coverage. Do NOT use for renaming an existing flag (breaking change — propose an alias instead) or for adding a brand-new subcommand (different scaffold under SymfonyCommand).

Adds a framework-aware tuning profile by creating profiles/<framework>.json, registering it in src/Cli/ProjectProfileDetector.php (detectIn() + KNOWN_PROFILES), and adding a marker-detection unit test in tests/Unit/Cli/ProjectProfileDetectorTest.php. Use when the user says 'add profile for <framework>', 'auto-tune for <framework>', 'support <framework> conventions', or 'detect <CMS> projects'. Capabilities: writes JSON profile shape (exclude, kinds, min_block_size, min_cluster_impact), inserts detection rule in correct specificity order, updates KNOWN_PROFILES constant, adds detection test + updates testRegistryLoadsBundledProfiles. Do NOT use for one-off corpus tuning (that is `--auto-tune` driven by src/Cli/AutoTuner.php), for editing existing profile values without adding a new framework, or for adding non-PHP-ecosystem profiles.

Generates a PHPUnit 10.5 unit test under tests/Unit/<Subns>/<Class>Test.php that mirrors src/ layout, declares namespace Phpdup\Tests\Unit\<Sub>, uses Symfony NullOutput when invoking pipeline stages, and synthesizes Cluster/Block fixtures for reporter/ranker tests. Honors phpunit.xml's failOnWarning=true and failOnNotice=true. Use when the user says 'add test', 'write a unit test', 'cover this with phpunit', 'add phpunit coverage', or after creating a new src/ class with no matching test. Do NOT use for: golden snapshot tests under tests/Golden/ (those are regenerated with UPDATE_SNAPSHOTS=1), integration tests under tests/Integration/, or fixture .php files under tests/Fixtures/.

Adds a data-access/repository class in src/ using Workerman\MySQL\Connection with parameterized $db->query('... WHERE id = ?', [$id]), the project's sprintf-based generateUuid() helper, and metadata_json hydration via json_decode. Use when the user says 'add repository', 'add table', 'CRUD', 'query the database', 'data access layer', or touches src/Auth/UserRepository.php, src/Media/Library/ItemRepository.php, or src/Session/SessionManager.php. Do NOT use for PDO, mysqli, raw mysqli_* calls, Eloquent/Doctrine ORMs, or migration file authoring (use migrations/NNN_*.sql directly for schema).

Creates HTTP controller classes in src/Server/Http/Controllers/ following the project's Request/Response pattern with chained (new Response())->status()->json() calls, constructor-injected services, and $params array from {id} route matches. Registers the route in src/Server/Http/Router.php (API) or src/Server/WebPortal/WebPortalRouter.php (web portal). Use when user says 'add endpoint', 'new route', 'new controller', 'create API endpoint', 'add HTTP handler', or adds files to src/Server/Http/Controllers/. Do NOT use for WebSocket events (use websocket-event skill), static page rendering with Smarty templates (use smarty-page skill), or DLNA/UPnP protocol handlers (different stack in src/Dlna/).

Writes a PHPUnit 10 unit test under `tests/Unit/{Module}/{Class}Test.php` extending `PHPUnit\Framework\TestCase`, following the exact patterns in `tests/Unit/Auth/JwtHandlerTest.php` and `tests/Unit/Media/Library/ItemRepositoryTest.php` — uses `$this->createMock(Connection::class)` for `Workerman\MySQL\Connection` with `->method('query')->willReturn([['col' => 'val']])` for reads and `->expects($this->once())->method('query')->with($this->stringContains('SQL'), $this->callback(fn))` for writes. Use when the user says 'write a test', 'add unit test', 'TDD this', 'test this class', or adds files under `tests/Unit/`. Covers PSR-4 namespacing (`Phlix\Tests\Unit\{Module}`), constructor-injection mocking, return-value stubs, expectation-based assertions, and running with `vendor/bin/phpunit --testsuite Unit`. Do NOT use for JS tests (project has no JS test runner), integration/E2E tests that need a real DB (no integration testsuite is configured), or non-`tests/Unit/` paths.

Adds a new Smarty template under `public/templates/{section}/*.tpl` (extending `layouts/main.tpl` via `{extends}`/`{block name="main"}`) and a matching `renderXxx(Request $request): Response` method in `src/Server/WebPortal/PageRenderer.php` that builds `new \Smarty()`, calls `setTemplateDir($this->templateDir)`, assigns data, fetches the template, and returns `(new Response())->html(...)`. Use when user says 'add page', 'new template', 'render view', 'add a Smarty view', or modifies anything under `public/templates/` or `PageRenderer.php`. Do NOT use for JSON API endpoints (those live in `WebPortalRouter` and return `(new Response())->json(...)` — use the http-controller / api-endpoint skill instead), and do NOT use for layout partials in `public/templates/partials/` (those are `{include}`-only fragments with no PageRenderer method).

Registers a new WebSocket event handler via MessageHandler->on('event_name', fn($conn, $payload) => ...) and adds the corresponding constant to src/Server/WebSocket/Events.php (WebSocketEvents::*). Uses $conn->sendMessage('type', [...]) for replies and $handler->broadcast() / sendToUser() / sendToSession() for fan-out. Use when user says 'add websocket event', 'real-time message', 'syncplay event', 'broadcast event', or touches src/Server/WebSocket/MessageHandler.php. Do NOT use for HTTP routes (use http-controller), DLNA SSDP events, or REST API endpoints.

Writes, debugs, and refactors JavaScript code using modern ES2023+ features, async/await patterns, ESM module systems, and Node.js APIs. Use when building vanilla JavaScript applications, implementing Promise-based async flows, optimising browser or Node.js performance, working with Web Workers or Fetch API, or reviewing .js/.mjs/.cjs files for correctness and best practices.

Plan and review MySQL/InnoDB schema, indexing, query tuning, transactions, and operations. Use when creating or modifying MySQL tables, indexes, or queries; diagnosing slow/locking behavior; planning migrations; or troubleshooting replication and connection issues. Load when using a MySQL database.

PHPUnit testing best practices and conventions guide. This skill should be used when writing, reviewing, or refactoring PHPUnit tests to ensure consistent, maintainable, and effective test suites. Triggers on tasks involving test creation, test refactoring, test configuration, code coverage, data providers, mocking, or PHPUnit XML configuration.

Writes Jest tests for the phlix-mobile React Native app using preset `react-native`, placing files at `src/<dir>/__tests__/<file>.test.ts` with `@/*` path aliases and reusing global mocks from `jest.setup.js`. Use when user says 'write test', 'add jest test', 'cover this store', 'test this component', or mentions TDD for TS/TSX files under `src/`. Capabilities: Zustand store testing with `getState`/`setState` reset, component snapshot/render testing via `react-test-renderer`, axios manager tests with `jest.mock('./client')`, async/await assertions, coverage filtering. Do NOT use for native iOS Swift/XCTest or Android JUnit/Espresso tests, Metro/build config tests, or non-React-Native projects.

Adds or extends a native module bridge across src/native/types.ts, ios/LocalPods/PhlixPlayer/ (Swift + Obj-C RCT_EXTERN_MODULE), and android/app/src/main/java/com/phlixmobile/ (Kotlin @ReactProp/@ReactMethod). Keeps event names and prop signatures aligned across all three layers, handles cleanup/observer removal. Use when user says 'add native module', 'expose to JS', 'bridge ios/android player feature', or edits PhlixPlayerView.swift/PhlixPlayerView.kt. Do NOT use for pure JS features, JS-only components, or features that don't require native code.

Scaffolds a new screen in `src/screens/` using `React.FC` default export, `<SafeContainer>`, the project's dark palette (`#0f0f1a`/`#1a1a2e`/`#0066cc`), and `LoadingSpinner`/`ErrorView`/`EmptyState` fallbacks. Updates `src/screens/index.ts` and wires the route into `src/navigation/RootNavigator.tsx` + `src/types/navigation.ts`. Use when user says 'add screen', 'new page', 'add a route', 'create screen', or adds files under `src/screens/`. Do NOT use for non-screen UI (use `rn-component` instead), for the native player modal (already wired), or for stateless presentational widgets.

Scaffolds a new Zustand store under src/stores/ using the create<State>((set, get) => ({...})) pattern with typed State interface, initialState + reset(), optional AsyncStorage persistence via the phlix_ key prefix, and wires the hook into src/stores/index.ts. Use when the user says 'add a store', 'new zustand store', 'add state for X', 'persist X across launches', or creates a file under src/stores/. Do NOT use for modifying existing stores' actions, for ephemeral component-local state (use useState), or for non-Zustand state (Redux/Context/Recoil are not used in this codebase).

Shape Android build logic with Gradle, version catalogs, plugins, convention patterns, and toolchain compatibility.

Adds a new API manager class in `src/api/` using the singleton pattern (`apiClient.get<T>(...)`, `export const xManager = new XManager()`). Wires re-exports through `src/api/index.ts`, keeps snake_case DTO fields, and puts shared media/playback types in `src/types/`. Use when user says 'add api manager', 'new endpoint client', 'wrap /api/foo', or adds files under `src/api/`. Do NOT use for raw axios calls outside `src/api/`, modifying `client.ts` interceptors, or anything inside `src/stores/` (managers stay stateless — Zustand stores call into them).

Builds, optimizes, and debugs cross-platform mobile applications with React Native and Expo. Implements navigation hierarchies (tabs, stacks, drawers), configures native modules, optimizes FlatList rendering with memo and useCallback, and handles platform-specific code for iOS and Android. Use when building a React Native or Expo mobile app, setting up navigation, integrating native modules, improving scroll performance, handling SafeArea or keyboard input, or configuring Expo SDK projects.

Master React Navigation - stacks, tabs, drawers, deep linking, and TypeScript integration

Adds a new server endpoint as a method on `app/js/api/ApiClient.js` and exposes it via the matching singleton manager (`AuthManager`, `SessionManager`, `LibraryManager`, `PlayerManager`). Use when the user says 'add endpoint', 'new API method', 'wrap /Items/...', 'call the server for X', or adds code under `app/js/api/`. Capabilities: writes the `ApiClient` method using `this.request(method, path, body, options)`, builds query strings with `URLSearchParams`, throws `ApiError` on failure, exposes a thin manager wrapper that logs via `Logger.error`, and adds matching Jest tests under `tests/unit/api/`. Do NOT use for direct `fetch` calls from views/components, for HLS `.m3u8` stream URLs (those go through `app/js/player/HlsPlayer.js`), for new auth flows that change token/session storage shape, or for changes to the device-profile payload itself.

Adds a new server endpoint as a method on `app/js/api/ApiClient.js` and exposes it via the appropriate manager (`AuthManager`, `SessionManager`, `LibraryManager`, `PlayerManager`). Uses `this.request(method, path, body, options)` with `URLSearchParams` for query strings and `ApiError` for failures. Use when user says 'add endpoint', 'new API method', 'call /Items/...', or adds code under `app/js/api/`. Do NOT use for direct `fetch` calls from views, for HLS streaming URLs (those go through `getItemPlaybackInfo`), or for editing the `deviceProfile` shape.

Adds a Jest jsdom unit test at tests/unit/<layer>/<File>.test.js mirroring the source layout under app/js/<layer>/, importing the class (not the singleton) for fresh beforeEach instances. Follows the describe/describe/it('should …') pattern from tests/unit/api/ApiClient.test.js, tests/unit/utils/Helpers.test.js, and tests/unit/remote/KeyMapping.test.js. Use when user says 'write a test', 'add unit test', 'test this', 'jest test', or after adding new code to app/js/. Do NOT use for integration tests under tests/integration/ (directory does not exist yet — the npm script passes empty), Tizen widget signing tests, or non-Jest test runners.

Wires a new Samsung Tizen remote action by updating `KEY_MAP`, `isRepeatable`/`isImmediate` classification, and `getDisplayName` in `app/js/remote/KeyMapping.js`, then handles it in `PlayerRemoteHandler.js` or the global navigation handler. Use when user says 'add remote key', 'handle MediaPlayPause', 'map color button', 'wire a new remote action', or modifies anything under `app/js/remote/`. Capabilities: keycode-to-action mapping, repeat vs immediate classification, display-name registration, handler wiring during playback vs navigation, KeyMapping unit-test updates. Do NOT use for raw `document.addEventListener('keydown')` outside `RemoteManager` (forbidden — all remote input flows through the singleton), for adding browser/mouse/pointer events (TV has none), or for editing `hls.js` quality keys (use the player skill instead).

Creates a new view class under app/js/ui/ following the show()/hide()/load(params) lifecycle, registers it in App.js view map, and wires a hash route via Router.addRoute('/path', handler). Handles manual focus with .focusable + .selected classes and Enter keydown (no pointer/mouse events). Use when user says 'add view', 'add screen', 'new page', 'add route', or creates files under app/js/ui/. Do NOT use for player overlay controls (extend PlayerView.js methods like toggleInfoPanel/cycleSubtitles instead), for non-routed reusable components, or for API/manager classes (those live under app/js/api/).

Dispatches work to the TaskWorker at `Text://127.0.0.1:2208` using `AsyncTcpConnection`, sending JSON `{type: 'function_name', args: {}}`. Also covers periodic task scheduling via core `Timer::add()` (from `Workerman\Timer`) in `onWorkerStart`. Use when user says 'dispatch task', 'run async', 'call task worker', 'schedule periodic', 'async dispatch', or needs to call a `Tasks/*.php` function from a Worker context. Do NOT use for direct synchronous function calls within the same process.

Creates a new PHP task function in `Tasks/` following the project's auto-load pattern. Each file exports one function named after the file (e.g. `Tasks/my_task.php` → `function my_task($args)`). Handles available globals: `$worker_db`, `$global`, `$influx_v2_database`, `$memcache`, `$redis`. Use when user says 'add task', 'new task function', 'create task', 'task worker function', or adds/modifies files in `Tasks/`. Do NOT use for modifying `Events.php`, adding Web endpoints, or creating Worker services.

Adds or modifies GatewayWorker event handling in Applications/Chat/Events.php. Use when user says 'handle message', 'on connect', 'gateway event', 'client message handler', 'broadcast to client', or needs to modify Events.php. Covers onConnect/onClose lifecycle hooks, msg* handler methods, Gateway::send* routing, session read/write, bindUid, joinGroup. Do NOT use for new Worker services, task dispatch to port 2208, or GlobalData timer setup.

Implements GlobalData CAS (compare-and-swap) locking for distributed coordination across Workerman processes. Pattern: `$global->cas($var, 0, time())` to acquire, `$global->$var = 0` to release; uses request-state tracking variable (`$var.'_request'`) for debugging. `$global` is a `\GlobalData\Client` instance connecting to `GLOBALDATA_IP:2207`. Use when user says 'lock between processes', 'prevent concurrent', 'CAS lock', 'share variable', 'global state', or coordinates work across task workers. Do NOT use for local single-process state.

Creates a new Workerman Worker service file in `Applications/Chat/start_*.php`. Use when user says 'add service', 'new worker', 'add process', 'new workerman component'. Handles boilerplate: use statements, buffer sizes (100MB), onConnect/onBufferFull/onBufferDrain/onError callbacks, GLOBAL_START guard, and start.php $services registration. Do NOT use for task functions in Tasks/*.php or gateway event handlers in Events.php.

Adds a new method to the `ApiClient` class in `src/renderer/utils/api.ts`. Defines exported TypeScript request/response interfaces (matching `MediaItem`/`Library`/`AuthResult` style), calls `this.request<T>(method, path, data)` so axios interceptors attach `Authorization: Bearer` and `X-Phlix-Session-ID` headers automatically against `${VITE_PHLIX_SERVER_URL}/api/v1`. Use `URLSearchParams` for GET query strings (see `getLibraryItems`). Use when user says 'add API call', 'new endpoint method', 'call /api/v1/...', or hits a Phlix Media Server route not yet wired. Do NOT use for raw `axios.create` outside `ApiClient` or for bypassing the `request()` helper.

Adds a new Electron IPC channel coordinated across main, preload, and renderer type definitions. Wires ipcMain.handle/ipcMain.on in src/main/index.ts, exposes via contextBridge.exposeInMainWorld in src/preload/index.ts, and types window.electronAPI in src/renderer/types/electron.d.ts. Listener helpers must return cleanup functions per existing pattern. Use when user says 'add IPC handler', 'expose to renderer', 'new electronAPI method', 'tray menu action', or modifies src/main/index.ts / src/preload/index.ts / src/renderer/types/electron.d.ts. Do NOT use for renderer-only logic, for changing existing IPC signatures without coordinated updates across all three files, or for adding non-IPC Electron APIs (BrowserWindow config, app lifecycle).

Adds a new React Router page in src/renderer/pages/, registers the route in App.tsx, and wires up navigation. Use when user says 'add page', 'new route', 'new screen', 'create page', or wants a top-level navigable view. Follows the project's useEffect + useState<T> + api.* + try/catch/finally setLoading(false) data-fetch pattern, with `<div className="loading-spinner" />` loading state. Do NOT use for modal/dialog flows, sub-views rendered inside an existing page, settings panels, or any non-routable UI.

Generates Vitest unit tests for the Electron renderer (stores, utilities, components) mirroring `tests/unit/api.test.ts`. Use when the user says 'write test', 'add unit test', 'cover this with vitest', 'add vitest spec', or adds files under `tests/unit/`. Produces tests that use jsdom env, the `localStorage` mock from `src/renderer/test-setup.ts`, and reset `auth_token`/`session_id`/`device_id` in `beforeEach`. Do NOT use for Playwright/E2E tests, for `src/main/**` Electron main-process code (needs a node env + electron mocks), or for `src/preload/**` bridge code.

Creates a new Zustand store in src/renderer/stores/ following the create<State>((set) => ({ ...initialState, action: () => set({...}) })) pattern from authStore.ts/playbackStore.ts/uiStore.ts. Defines the state interface with both data fields and action methods, prefixes unused setter args with _, calls api.* methods inside async actions with try/catch and electron-log/console.error logging, exposes a useNameStore hook. Use when user says 'add store', 'new zustand store', 'manage X state globally', or adds files to src/renderer/stores/. Do NOT use for component-local state (use useState), for trivial UI toggles already covered by uiStore, or for main-process state (Electron main uses electron-store, not Zustand).

Creates a new SessionHandlerInterface implementation in src/. Scaffolds all 9 required methods (open, close, read, write, destroy, gc, create_sid, validateId, updateTimestamp) with correct PHP 8.0+ return types and secure create_sid(). Use when user says 'add handler', 'new backend', 'implement session handler for X', or creates a file in src/. Do NOT use for modifying existing handlers.

Runs the full composer test suite (phpcs + phpstan + phpunit) and interprets failures for the session-samurai project. Use when the user says 'run tests', 'check code', 'does it pass', 'verify my changes', or before committing. Knows phpcs uses phpcs.xml (PSR-12 with exclusions), phpstan uses phpstan.neon (level: max, src/ only), and phpunit bootstraps via tests/Bootstrap.php with optional TestConfiguration.php. Do NOT use mid-refactor when tests are intentionally broken.

Creates a PHPUnit test class in tests/src/ for a SessionHandlerInterface implementation. Use when user says 'add tests', 'write tests for handler', or when a new handler is created without tests. Generates testOpen, testClose, testRead, testWrite, testDestroy, testGc, testCreateSid, testValidateId, testUpdateTimestamp following MySessionHandlerTest.php patterns. Do NOT use for non-handler test classes or general PHPUnit scaffolding.

Creates a new CLI script in `bin/` that instantiates `\Detain\Cpanel\Cpanel` with `argv[1]`/`argv[2]` credentials, calls a method, and prints results. Use when user says 'add script', 'create CLI tool', 'new bin file', or needs a command-line wrapper for a Cpanel API method. Do NOT use for library code in `src/` or test code in `tests/`.

Adds a new public method to `src/Cpanel.php` following the validate→get pattern. Validates required args with `array_key_exists`, calls `validateIP()` or `validateID()`, then delegates to `$this->get('XMLfunctionName.cgi', $args)`. Use when user says 'add method', 'new API call', 'implement endpoint', or adds a cPanel CGI function. Do NOT use for modifying the private `get()` or `formatResult()` internals.

Implements incomplete test stubs in tests/CpanelTest.php by replacing markTestIncomplete() with real assertions. Use when user says 'implement test', 'write test for', 'complete test stub', or references a src/Cpanel.php method lacking coverage. Do NOT use for adding new test classes or new test methods that don't already exist as stubs.

Adds a new country postal code format to src/Validator.php $formats array and optional $zipNames entry. Use when user says 'add country', 'support new postal code', 'add format for XX', or requests a new ISO country code. Includes format string syntax (#=digit, @=letter) and corresponding PHPUnit test in tests/Detain/Tests/ZipZapper/ValidatorTest.php. Do NOT use for modifying existing country entries or updating the full dataset from Wikipedia (use bin/parse.php for that).

Updates the $formats array in src/Validator.php from Wikipedia's postal codes list via bin/parse.php. Use when user says 'update formats', 'refresh postal codes', 'sync from Wikipedia', or 'formats are outdated'. Explains the parse.php workflow, MyAdmin dependency requirement, and how to paste output into Validator.php. Do NOT use for adding a single country manually — that is a direct edit to src/Validator.php.

Creates PHPUnit test cases for Validator methods in tests/Detain/Tests/ZipZapper/ValidatorTest.php following existing patterns. Use when user says 'add test', 'write test for country', 'test isValid', 'test getFormats', 'test hasCountry', or 'test getZipName'. Covers isValid(), hasCountry(), getFormats(), getZipName(), and ValidationException throwing. Do NOT use for integration tests, parser tests, or bin/parse.php testing.

Adds a new action method to `src/LiteSpeed.php` following the param-build → req() pattern. Sets params on `$this->params` with `rawurlencode()`, validates inputs against `$valid*` arrays, returns array or false. Use when user says 'add method', 'new action', 'implement endpoint', or names a LiteSpeed eService action. Do NOT use for modifying `req()` itself or changing transport/auth logic.

Documents and applies the project's error pattern: validation returns `['error' => 'msg']`, failed cURL returns `false`, errors accumulate in `$this->error[]`. Use when adding new methods, handling return values, or debugging failed API calls. Do NOT use for adding exceptions — the project intentionally avoids them, and do NOT use for non-LiteSpeed API integrations.

Creates PHPUnit tests in `tests/` for `Detain\LiteSpeed\LiteSpeed` bootstrapped via `vendor/autoload.php`. Covers input validation (returns `['error'=>...]`) and response parsing by partially mocking `req()` with Mockery. Use when user says 'write test', 'add test', 'test method', or 'coverage'. Do NOT use for integration tests that hit the live LiteSpeed API at store.litespeedtech.com.