{"owner":"wailsapp","repo":"wails","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"files":{"AGENTS.md":"# AI Agent Instructions for Wails v3\n\n## Issue Tracking with GitHub\n\n**IMPORTANT**: GitHub Issues and pull requests are the authoritative trackers for this project. Do not create a parallel local issue database or markdown task list.\n\n### Workflow for AI Agents\n\n1. Search existing GitHub issues and pull requests before creating new work.\n2. Link implementation work to the relevant issue or pull request.\n3. File newly discovered actionable work as a GitHub issue with reproduction details, scope, and acceptance criteria.\n4. Use labels, milestones, and cross-references to express priority, release scope, and dependencies.\n5. Close issues only after the work is complete and verified; otherwise document why the item is deferred or no longer applicable.\n\n### Important Rules\n\n- Do not duplicate existing GitHub issues.\n- Keep issue descriptions current when scope or reproduction steps change.\n- Store AI-generated planning documents in `history/`, not the repository root;\n  the persistent root `IMPLEMENTATION.md` tracker described below is the exception.\n- **ALWAYS run `coderabbit --plain` before committing** to catch issues early.\n- All commits must use the `taliesin-ai` identity.\n- Never push until the user gives explicit manual confirmation.\n\n### Managing AI-Generated Planning Documents\n\nAI assistants often create planning and design documents during development:\n- PLAN.md, IMPLEMENTATION.md, ARCHITECTURE.md\n- DESIGN.md, CODEBASE_SUMMARY.md, INTEGRATION_PLAN.md\n- TESTING_GUIDE.md, TECHNICAL_DESIGN.md, and similar files\n\n**Best Practice: Use a dedicated directory for these ephemeral files**\n\n**Recommended approach:**\n- Create a `history/` directory in the project root\n- Store all ephemeral AI-generated planning/design docs in `history/`;\n  keep the persistent root `IMPLEMENTATION.md` tracker in place\n- Keep the repository root clean and focused on permanent project files\n- Only access `history/` when explicitly asked to review past planning\n\n**Example .gitignore entry (optional):**\n```\n# AI planning documents (ephemeral)\nhistory/\n```\n\n**Benefits:**\n- Clean repository root\n- Clear separation between ephemeral and permanent documentation\n- Easy to exclude from version control if desired\n- Preserves planning history for archeological research\n- Reduces noise when browsing the project\n\n## Frontend Runtime: Two Build Outputs\n\nThe TypeScript runtime in `v3/internal/runtime/desktop/@wailsio/runtime` produces **two**\nindependent artifacts, and rebuilding one but not the other is a common and confusing\nmistake:\n\n| task | output | consumed by |\n|---|---|---|\n| `task v3:runtime:build:assets` | `v3/internal/assetserver/bundledassets/runtime.js` (+ `.debug.js`) | the webview, served at `/wails/runtime.js` |\n| `task v3:runtime:build:package` | `dist/` in the package directory | an app's frontend, via `node_modules` |\n\nAfter changing anything under `src/`, rebuild **both**. CI verifies the committed bundles\nmatch `build:assets` output exactly, so the bundles must be committed with the change.\n\nAn application imports `@wailsio/runtime` from npm, so it will not see runtime changes made\nin this checkout. To test an app against the working tree:\n\n```bash\ntask v3:install-runtime -- ./path/to/your-app/frontend\n```\n\nUndo with `npm install @wailsio/runtime@latest` in the same directory.\n\n## Subsystem References\n\nSome subsystems have a dedicated internals page written for agents. Read the relevant one\nbefore changing that code — several of its decisions look arbitrary until you know which\nmeasured bug they prevent.\n\n- **Streams** (`pkg/application/stream*.go`, `runtime/.../stream.ts`):\n  `docs/src/content/docs/guides/advanced/streams-internals.mdx`. Covers the held-poll\n  design, the buffer constants and how to pick them, session and connection lifecycle,\n  transport selection, and what is unfinished. To convert an existing WebSocket\n  implementation, follow `docs/src/content/docs/guides/streams-from-websockets.mdx` —\n  a mechanical checklist, including the differences that break silently.\n\n## Implementation Tracking (IMPLEMENTATION.md)\n\n**IMPORTANT**: The `IMPLEMENTATION.md` file at the repository root is a **persistent tracking document** for the GTK4 / WebKitGTK 6.0 / GTK3-legacy implementation work. It is NOT an ephemeral planning document.\n\nAs of 2026-05-16 (issue #5459), GTK4 + WebKitGTK 6.0 is the **default** Linux stack; GTK3 + WebKit2GTK 4.1 is a legacy opt-in (`-tags gtk3`) for one v3 cycle and is scheduled for removal in v3.1. The default-flip rationale is recorded in `IMPLEMENTATION.md` Decision 1.1.\n\n### Requirements\n\n1. **Update with EVERY commit** that touches GTK4/WebKitGTK 6.0 or legacy GTK3 code\n2. **Track all architectural decisions** with context, decision, and rationale\n3. **Maintain progress status** for each implementation phase\n4. **Document API differences** between the GTK4 default and GTK3 legacy paths\n5. **Keep file references** accurate and up-to-date\n\n### What to Update\n\n- Phase completion status (✅ COMPLETE, 🔄 IN PROGRESS, 📋 PENDING)\n- New decisions made during implementation\n- Files created or modified\n- Changelog entries with dates\n- TODO items discovered during work\n\n### Commit Message Pattern\n\nWhen updating IMPLEMENTATION.md:\n```\ndocs: update implementation tracker for [phase/feature]\n```\n\n## Landing the Plane (Session Completion)\n\n**When ending a work session**, complete the applicable steps below. Never push without explicit manual confirmation from the user.\n\n**MANDATORY WORKFLOW:**\n\n1. **File issues for remaining work** - Create issues for anything that needs follow-up\n2. **Run quality gates** (if code changed) - Tests, linters, builds\n3. **Update issue status** - Close finished work, update in-progress items\n4. **Prepare for remote sync**:\n   ```bash\n   git status\n   ```\n   When the worktree is clean and synchronization is intended, run\n   `git pull --rebase`.\n   Run `git push` only after the user explicitly confirms it.\n5. **Clean up** - Review stashes and remove only obsolete ones; prune remote branches\n6. **Verify** - All intended changes are present and committed when requested\n7. **Hand off** - Provide context for next session\n\n**CRITICAL RULES:**\n- Use the `taliesin-ai` identity for every commit.\n- Do not push without explicit manual confirmation.\n- Report clearly whether changes are uncommitted, committed locally, or pushed.\n"}}