{"owner":"beeware","repo":"toga","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# Toga - Agent Development Guide\n\n<!-- SPECKIT START -->\nFor additional context about technologies to be used, project structure, shell commands, and other important information, read the current plan\n<!-- SPECKIT END -->\n\nThis file tells autonomous coding agents (and human contributors using agent tools) how to be productive in this repository without breaking it. It is operational guidance; the binding rules live in `.specify/memory/constitution.md` and the contribution docs under `docs/en/how-to/contribute/`. When this file disagrees with either, the constitution wins.\n\n## What Toga is\n\nToga is a Python-native, OS-native GUI toolkit published under BSD-3-Clause as part of the BeeWare suite. A single `toga-core` API is rendered by a platform-specific backend so that one Python codebase produces native apps on macOS, Windows, Linux, iOS, Android, Web, and terminal.\n\n## Repository layout\n\n| Path | What it contains |\n| --- | --- |\n| `core/` | `toga-core` — the public API and shared widget contracts. |\n| `travertino/` | Style and layout engine used by `core`. |\n| `dummy/` | Reference headless backend; MUST implement the full core API so core tests can run without a GUI. |\n| `cocoa/` | macOS backend. |\n| `gtk/` | Linux/GTK backend (GTK3 stable, GTK4 experimental). |\n| `winforms/` | Windows backend. |\n| `iOS/` | iOS backend. |\n| `android/` | Android backend. |\n| `textual/` | Terminal backend. |\n| `web/` | Web backend. |\n| `qt/` | Linux/Qt backend. |\n| `positron/` | Briefcase plugin for generating apps where the UI has been defined with web tools. Similar to Electron, but using Python for the web server |\n| `testbed/` | Briefcase app used to validate backend behaviour on a real platform. |\n| `docs/en/` | User and contributor documentation (MkDocs, `mkdocs.en.yml`). |\n| `changes/` | Towncrier fragments (`<issue>.<kind>.md`) — one per user-visible change. |\n| `examples/`, `demo/` | Standalone sample apps. |\n| `.specify/` | SpecKit workflow assets (constitution, templates, extensions). |\n\nDo not create new top-level directories without a clear constitutional reason; extend existing ones.\n\n## Non-negotiables (from the constitution)\n\n1. **Backend parity.** A new `toga-core` API MUST have a concrete implementation plan for every production backend. The Dummy backend MUST always implement the full surface.\n2. **Native behaviour.** Production backends MUST delegate to the native toolkit. No emulated/custom-drawn widgets without documented justification.\n3. **Comprehensive tests (NON-NEGOTIABLE).** 100% line coverage for `core` and `travertino`. Backend changes MUST be exercised via `testbed/`. Bug fixes MUST include a regression test that fails before the fix.\n4. **Documented change.** Every user-visible change MUST include a `changes/<issue>.<kind>.md` fragment and updated docs. Breaking changes require a deprecation release.\n5. **Contributor accountability.** The submitter owns the diff, regardless of AI assistance. Follow the BeeWare Code of Conduct and AI Policy.\n\nAny PR failing one of these is rejected, not waived.\n\n## Toolchain\n\n- **Python**: 3.10–3.14 (see `core/pyproject.toml` classifiers).\n- **Task runner**: `tox` (with `tox-uv`). Install the dev tooling via `uv pip install --group dev` at the repo root, or let `tox` bootstrap.\n- **Lint/format**: `ruff` (check + format), `codespell`, `rumdl` (Markdown), configured in root `pyproject.toml`.\n- **Pre-commit**: `pre-commit run --all-files` — MUST pass before PR.\n- **Packaging / testbed driver**: `briefcase`.\n- **Release notes**: `towncrier` (config in root `pyproject.toml`).\n- **Docs**: MkDocs; built with the `docs` dependency group.\n\nDo not replace or bypass these tools. Add new dependencies only with a clear need and a compatible license (BSD-3-Clause friendly).\n\n## Canonical commands\n\nRun from the repository root unless noted.\n\n```console\n# Everything pre-commit checks (ruff, format, codespell, rumdl, etc.)\npre-commit run --all-files\n\n# Core + Travertino test suites with coverage (MUST be 100%)\ntox -m test\n\n# Just core\ntox -m test-core\n\n# Just Travertino\ntox -m test-trav\n\n# A single test file against core\ntox -e py-cov -- core/tests/path/to/test_file.py\n\n# A single test file against Travertino\ntox -e py-trav -- travertino/tests/path/to/test_file.py\n\n# Towncrier draft (preview assembled release notes)\ntox -e towncrier-check\n\n# Docs lint\ntox -e docs-lint\n```\n\n### Testbed (backend validation)\n\nThe core suite uses the Dummy backend. Real backend behaviour is validated through the testbed app. Install only the backend under test in your virtualenv, then:\n\n```console\n# Desktop (from testbed/)\nbriefcase dev --app testbed --test\n\n# GTK variants (Linux)\nbriefcase dev --app testbed --test\nTOGA_GTK=4 TOGA_GTKLIB=None briefcase dev --app testbed --test\nTOGA_GTK=4 TOGA_GTKLIB=Adw briefcase dev --app testbed --test\n\n# Qt (Linux)\nbriefcase dev --app testbed-qt --test\n\n# Textual (Linux)\nbriefcase dev --app testbed-textual --test\n\n# Mobile (requires the relevant SDK/toolchain)\nbriefcase run android --app testbed --test\nbriefcase run iOS --app testbed --test   # macOS host only\n\n# Subset with slow mode for visual inspection\nbriefcase dev --app testbed --test -- tests/widgets/test_button.py --slow\n```\n\n**Do not touch the keyboard/mouse while the testbed is running** — it drives input programmatically and will desync.\n\n## Change notes\n\nEvery user-visible PR needs a file in `changes/`:\n\n```text\nchanges/<issue_or_pr_number>.<kind>.md\n```\n\n`<kind>` MUST be one of: `feature`, `bugfix`, `removal`, `doc`, `misc`. Content is one or more sentences of past-tense prose describing the user-visible change. `misc` entries are hidden from release notes and appropriate for purely internal changes. Do not edit `docs/en/about/releases.md` directly; towncrier assembles it at release time.\n\n## Coding conventions\n\n- Follow the Toga code style guide linked from `CONTRIBUTING.md`. Ruff enforces most of it; do not disable rules locally.\n- Keep public API surface minimal and documented. New public names MUST appear in reference docs under `docs/en/reference/api/`.\n- Type hints: use them on public API; keep them consistent with the `.pyi` stub (`core/src/toga/__init__.pyi`) when applicable. That stub is excluded from Ruff — hand-edit it carefully.\n- `# pragma: no cover` is reserved for the cases already whitelisted in `tool.coverage.coverage_conditional_plugin.rules`. Do not introduce new ones to work around missing tests.\n- `filterwarnings = [\"error\"]` is set for pytest; warnings in tests are failures. Either fix the root cause or add a scoped, commented `pytest.warns(...)` / `filterwarnings` mark.\n- `isort` config in root `pyproject.toml` lists the first-party backend packages; add new packages there if you create one.\n\n## Documentation expectations\n\n- Every new public API, widget, or behavioural change MUST update `docs/en/` in the same PR.\n- Tutorials live under `docs/en/tutorial/`, how-tos under `docs/en/how-to/`, reference under `docs/en/reference/`, topic explanations under `docs/en/topics/`.\n- Build-time doc linting runs through `tox -e docs-lint`; fix anything it reports.\n- Markdown files in this project (including `AGENTS.md`, `docs/en/`, and `changes/` fragments) must **not** use hard line breaks to enforce an 80-character column limit. Each paragraph or list item must be written as a single unbroken line, regardless of its length. Let the reader's editor or renderer handle wrapping. This rule applies to all prose. Code blocks, directory trees, and other pre-formatted blocks are exempt — keep those readable within their own constraints. When writing or editing any `.md` file, do not insert newlines mid-sentence or mid-paragraph to stay within 80 columns.\n- Follow the BeeWare documentation style guide (linked from `CONTRIBUTING.md`).\n\n## Pull-request workflow\n\n1. Branch off `main` with a descriptive name. Do not push to `main`.\n2. Make the smallest change that addresses one issue. Avoid scope creep; file a separate issue/PR for drive-by refactors.\n3. Before opening the PR, run locally:\n    - `pre-commit run --all-files`\n    - `tox -m test` (expect 100% coverage)\n    - Testbed on any backend the change affects\n4. Include in the PR:\n    - A `changes/<issue>.<kind>.md` fragment\n    - Docs updates when user-visible\n    - A description naming the issue closed and the backends exercised\n5. CI MUST be green. Reviewers confirm the five constitutional principles; failures are fixed, not waived.\n6. Default merge strategy is squash; the squash message is what users will read, so make it describe the user-visible change.\n\n## Agent-specific rules\n\nAgents operating in this repo MUST:\n\n- Load `.specify/memory/constitution.md` before any change that affects public API, backends, test coverage, or release tooling.\n- Prefer editing existing files over creating new ones. Never proactively create new top-level files or directories.\n- Keep the `<!-- SPECKIT START --> ... <!-- SPECKIT END -->` block at the top of this file intact; SpecKit commands inject plan context there.\n- Never add `# pragma: no cover`, `# noqa`, or disable Ruff/codespell rules inline to pass CI; diagnose and fix the underlying issue.\n- Never commit secrets, API keys, `.env` files, or contributor PII.\n- Never rewrite Git history on `main` or force-push shared branches.\n- When uncertain about backend parity or API shape, open an issue or discussion before implementing; Toga favours design-first for anything non-trivial (see `docs/en/how-to/contribute/how/propose-feature.md`).\n- Disclose AI assistance in the PR description where it is material to review, per the BeeWare AI Policy.\n\n## Where to look next\n\n- `CONTRIBUTING.md` — entry point for all contributors.\n- `.specify/memory/constitution.md` — binding project principles.\n- `docs/en/how-to/contribute/` — style guides, PR process, review guide, scope-creep guide, AI policy.\n- `docs/en/reference/platforms/` — per-backend requirements and status.\n- Toga documentation site: <https://toga.beeware.org>\n- BeeWare community and Code of Conduct: <https://beeware.org>\n"},"files":{"AGENTS.md":"# Toga - Agent Development Guide\n\n<!-- SPECKIT START -->\nFor additional context about technologies to be used, project structure, shell commands, and other important information, read the current plan\n<!-- SPECKIT END -->\n\nThis file tells autonomous coding agents (and human contributors using agent tools) how to be productive in this repository without breaking it. It is operational guidance; the binding rules live in `.specify/memory/constitution.md` and the contribution docs under `docs/en/how-to/contribute/`. When this file disagrees with either, the constitution wins.\n\n## What Toga is\n\nToga is a Python-native, OS-native GUI toolkit published under BSD-3-Clause as part of the BeeWare suite. A single `toga-core` API is rendered by a platform-specific backend so that one Python codebase produces native apps on macOS, Windows, Linux, iOS, Android, Web, and terminal.\n\n## Repository layout\n\n| Path | What it contains |\n| --- | --- |\n| `core/` | `toga-core` — the public API and shared widget contracts. |\n| `travertino/` | Style and layout engine used by `core`. |\n| `dummy/` | Reference headless backend; MUST implement the full core API so core tests can run without a GUI. |\n| `cocoa/` | macOS backend. |\n| `gtk/` | Linux/GTK backend (GTK3 stable, GTK4 experimental). |\n| `winforms/` | Windows backend. |\n| `iOS/` | iOS backend. |\n| `android/` | Android backend. |\n| `textual/` | Terminal backend. |\n| `web/` | Web backend. |\n| `qt/` | Linux/Qt backend. |\n| `positron/` | Briefcase plugin for generating apps where the UI has been defined with web tools. Similar to Electron, but using Python for the web server |\n| `testbed/` | Briefcase app used to validate backend behaviour on a real platform. |\n| `docs/en/` | User and contributor documentation (MkDocs, `mkdocs.en.yml`). |\n| `changes/` | Towncrier fragments (`<issue>.<kind>.md`) — one per user-visible change. |\n| `examples/`, `demo/` | Standalone sample apps. |\n| `.specify/` | SpecKit workflow assets (constitution, templates, extensions). |\n\nDo not create new top-level directories without a clear constitutional reason; extend existing ones.\n\n## Non-negotiables (from the constitution)\n\n1. **Backend parity.** A new `toga-core` API MUST have a concrete implementation plan for every production backend. The Dummy backend MUST always implement the full surface.\n2. **Native behaviour.** Production backends MUST delegate to the native toolkit. No emulated/custom-drawn widgets without documented justification.\n3. **Comprehensive tests (NON-NEGOTIABLE).** 100% line coverage for `core` and `travertino`. Backend changes MUST be exercised via `testbed/`. Bug fixes MUST include a regression test that fails before the fix.\n4. **Documented change.** Every user-visible change MUST include a `changes/<issue>.<kind>.md` fragment and updated docs. Breaking changes require a deprecation release.\n5. **Contributor accountability.** The submitter owns the diff, regardless of AI assistance. Follow the BeeWare Code of Conduct and AI Policy.\n\nAny PR failing one of these is rejected, not waived.\n\n## Toolchain\n\n- **Python**: 3.10–3.14 (see `core/pyproject.toml` classifiers).\n- **Task runner**: `tox` (with `tox-uv`). Install the dev tooling via `uv pip install --group dev` at the repo root, or let `tox` bootstrap.\n- **Lint/format**: `ruff` (check + format), `codespell`, `rumdl` (Markdown), configured in root `pyproject.toml`.\n- **Pre-commit**: `pre-commit run --all-files` — MUST pass before PR.\n- **Packaging / testbed driver**: `briefcase`.\n- **Release notes**: `towncrier` (config in root `pyproject.toml`).\n- **Docs**: MkDocs; built with the `docs` dependency group.\n\nDo not replace or bypass these tools. Add new dependencies only with a clear need and a compatible license (BSD-3-Clause friendly).\n\n## Canonical commands\n\nRun from the repository root unless noted.\n\n```console\n# Everything pre-commit checks (ruff, format, codespell, rumdl, etc.)\npre-commit run --all-files\n\n# Core + Travertino test suites with coverage (MUST be 100%)\ntox -m test\n\n# Just core\ntox -m test-core\n\n# Just Travertino\ntox -m test-trav\n\n# A single test file against core\ntox -e py-cov -- core/tests/path/to/test_file.py\n\n# A single test file against Travertino\ntox -e py-trav -- travertino/tests/path/to/test_file.py\n\n# Towncrier draft (preview assembled release notes)\ntox -e towncrier-check\n\n# Docs lint\ntox -e docs-lint\n```\n\n### Testbed (backend validation)\n\nThe core suite uses the Dummy backend. Real backend behaviour is validated through the testbed app. Install only the backend under test in your virtualenv, then:\n\n```console\n# Desktop (from testbed/)\nbriefcase dev --app testbed --test\n\n# GTK variants (Linux)\nbriefcase dev --app testbed --test\nTOGA_GTK=4 TOGA_GTKLIB=None briefcase dev --app testbed --test\nTOGA_GTK=4 TOGA_GTKLIB=Adw briefcase dev --app testbed --test\n\n# Qt (Linux)\nbriefcase dev --app testbed-qt --test\n\n# Textual (Linux)\nbriefcase dev --app testbed-textual --test\n\n# Mobile (requires the relevant SDK/toolchain)\nbriefcase run android --app testbed --test\nbriefcase run iOS --app testbed --test   # macOS host only\n\n# Subset with slow mode for visual inspection\nbriefcase dev --app testbed --test -- tests/widgets/test_button.py --slow\n```\n\n**Do not touch the keyboard/mouse while the testbed is running** — it drives input programmatically and will desync.\n\n## Change notes\n\nEvery user-visible PR needs a file in `changes/`:\n\n```text\nchanges/<issue_or_pr_number>.<kind>.md\n```\n\n`<kind>` MUST be one of: `feature`, `bugfix`, `removal`, `doc`, `misc`. Content is one or more sentences of past-tense prose describing the user-visible change. `misc` entries are hidden from release notes and appropriate for purely internal changes. Do not edit `docs/en/about/releases.md` directly; towncrier assembles it at release time.\n\n## Coding conventions\n\n- Follow the Toga code style guide linked from `CONTRIBUTING.md`. Ruff enforces most of it; do not disable rules locally.\n- Keep public API surface minimal and documented. New public names MUST appear in reference docs under `docs/en/reference/api/`.\n- Type hints: use them on public API; keep them consistent with the `.pyi` stub (`core/src/toga/__init__.pyi`) when applicable. That stub is excluded from Ruff — hand-edit it carefully.\n- `# pragma: no cover` is reserved for the cases already whitelisted in `tool.coverage.coverage_conditional_plugin.rules`. Do not introduce new ones to work around missing tests.\n- `filterwarnings = [\"error\"]` is set for pytest; warnings in tests are failures. Either fix the root cause or add a scoped, commented `pytest.warns(...)` / `filterwarnings` mark.\n- `isort` config in root `pyproject.toml` lists the first-party backend packages; add new packages there if you create one.\n\n## Documentation expectations\n\n- Every new public API, widget, or behavioural change MUST update `docs/en/` in the same PR.\n- Tutorials live under `docs/en/tutorial/`, how-tos under `docs/en/how-to/`, reference under `docs/en/reference/`, topic explanations under `docs/en/topics/`.\n- Build-time doc linting runs through `tox -e docs-lint`; fix anything it reports.\n- Markdown files in this project (including `AGENTS.md`, `docs/en/`, and `changes/` fragments) must **not** use hard line breaks to enforce an 80-character column limit. Each paragraph or list item must be written as a single unbroken line, regardless of its length. Let the reader's editor or renderer handle wrapping. This rule applies to all prose. Code blocks, directory trees, and other pre-formatted blocks are exempt — keep those readable within their own constraints. When writing or editing any `.md` file, do not insert newlines mid-sentence or mid-paragraph to stay within 80 columns.\n- Follow the BeeWare documentation style guide (linked from `CONTRIBUTING.md`).\n\n## Pull-request workflow\n\n1. Branch off `main` with a descriptive name. Do not push to `main`.\n2. Make the smallest change that addresses one issue. Avoid scope creep; file a separate issue/PR for drive-by refactors.\n3. Before opening the PR, run locally:\n    - `pre-commit run --all-files`\n    - `tox -m test` (expect 100% coverage)\n    - Testbed on any backend the change affects\n4. Include in the PR:\n    - A `changes/<issue>.<kind>.md` fragment\n    - Docs updates when user-visible\n    - A description naming the issue closed and the backends exercised\n5. CI MUST be green. Reviewers confirm the five constitutional principles; failures are fixed, not waived.\n6. Default merge strategy is squash; the squash message is what users will read, so make it describe the user-visible change.\n\n## Agent-specific rules\n\nAgents operating in this repo MUST:\n\n- Load `.specify/memory/constitution.md` before any change that affects public API, backends, test coverage, or release tooling.\n- Prefer editing existing files over creating new ones. Never proactively create new top-level files or directories.\n- Keep the `<!-- SPECKIT START --> ... <!-- SPECKIT END -->` block at the top of this file intact; SpecKit commands inject plan context there.\n- Never add `# pragma: no cover`, `# noqa`, or disable Ruff/codespell rules inline to pass CI; diagnose and fix the underlying issue.\n- Never commit secrets, API keys, `.env` files, or contributor PII.\n- Never rewrite Git history on `main` or force-push shared branches.\n- When uncertain about backend parity or API shape, open an issue or discussion before implementing; Toga favours design-first for anything non-trivial (see `docs/en/how-to/contribute/how/propose-feature.md`).\n- Disclose AI assistance in the PR description where it is material to review, per the BeeWare AI Policy.\n\n## Where to look next\n\n- `CONTRIBUTING.md` — entry point for all contributors.\n- `.specify/memory/constitution.md` — binding project principles.\n- `docs/en/how-to/contribute/` — style guides, PR process, review guide, scope-creep guide, AI policy.\n- `docs/en/reference/platforms/` — per-backend requirements and status.\n- Toga documentation site: <https://toga.beeware.org>\n- BeeWare community and Code of Conduct: <https://beeware.org>\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# Toga - Agent Development Guide\n\n<!-- SPECKIT START -->\nFor additional context about technologies to be used, project structure, shell commands, and other important information, read the current plan\n<!-- SPECKIT END -->\n\nThis file tells autonomous coding agents (and human contributors using agent tools) how to be productive in this repository without breaking it. It is operational guidance; the binding rules live in `.specify/memory/constitution.md` and the contribution docs under `docs/en/how-to/contribute/`. When this file disagrees with either, the constitution wins.\n\n## What Toga is\n\nToga is a Python-native, OS-native GUI toolkit published under BSD-3-Clause as part of the BeeWare suite. A single `toga-core` API is rendered by a platform-specific backend so that one Python codebase produces native apps on macOS, Windows, Linux, iOS, Android, Web, and terminal.\n\n## Repository layout\n\n| Path | What it contains |\n| --- | --- |\n| `core/` | `toga-core` — the public API and shared widget contracts. |\n| `travertino/` | Style and layout engine used by `core`. |\n| `dummy/` | Reference headless backend; MUST implement the full core API so core tests can run without a GUI. |\n| `cocoa/` | macOS backend. |\n| `gtk/` | Linux/GTK backend (GTK3 stable, GTK4 experimental). |\n| `winforms/` | Windows backend. |\n| `iOS/` | iOS backend. |\n| `android/` | Android backend. |\n| `textual/` | Terminal backend. |\n| `web/` | Web backend. |\n| `qt/` | Linux/Qt backend. |\n| `positron/` | Briefcase plugin for generating apps where the UI has been defined with web tools. Similar to Electron, but using Python for the web server |\n| `testbed/` | Briefcase app used to validate backend behaviour on a real platform. |\n| `docs/en/` | User and contributor documentation (MkDocs, `mkdocs.en.yml`). |\n| `changes/` | Towncrier fragments (`<issue>.<kind>.md`) — one per user-visible change. |\n| `examples/`, `demo/` | Standalone sample apps. |\n| `.specify/` | SpecKit workflow assets (constitution, templates, extensions). |\n\nDo not create new top-level directories without a clear constitutional reason; extend existing ones.\n\n## Non-negotiables (from the constitution)\n\n1. **Backend parity.** A new `toga-core` API MUST have a concrete implementation plan for every production backend. The Dummy backend MUST always implement the full surface.\n2. **Native behaviour.** Production backends MUST delegate to the native toolkit. No emulated/custom-drawn widgets without documented justification.\n3. **Comprehensive tests (NON-NEGOTIABLE).** 100% line coverage for `core` and `travertino`. Backend changes MUST be exercised via `testbed/`. Bug fixes MUST include a regression test that fails before the fix.\n4. **Documented change.** Every user-visible change MUST include a `changes/<issue>.<kind>.md` fragment and updated docs. Breaking changes require a deprecation release.\n5. **Contributor accountability.** The submitter owns the diff, regardless of AI assistance. Follow the BeeWare Code of Conduct and AI Policy.\n\nAny PR failing one of these is rejected, not waived.\n\n## Toolchain\n\n- **Python**: 3.10–3.14 (see `core/pyproject.toml` classifiers).\n- **Task runner**: `tox` (with `tox-uv`). Install the dev tooling via `uv pip install --group dev` at the repo root, or let `tox` bootstrap.\n- **Lint/format**: `ruff` (check + format), `codespell`, `rumdl` (Markdown), configured in root `pyproject.toml`.\n- **Pre-commit**: `pre-commit run --all-files` — MUST pass before PR.\n- **Packaging / testbed driver**: `briefcase`.\n- **Release notes**: `towncrier` (config in root `pyproject.toml`).\n- **Docs**: MkDocs; built with the `docs` dependency group.\n\nDo not replace or bypass these tools. Add new dependencies only with a clear need and a compatible license (BSD-3-Clause friendly).\n\n## Canonical commands\n\nRun from the repository root unless noted.\n\n```console\n# Everything pre-commit checks (ruff, format, codespell, rumdl, etc.)\npre-commit run --all-files\n\n# Core + Travertino test suites with coverage (MUST be 100%)\ntox -m test\n\n# Just core\ntox -m test-core\n\n# Just Travertino\ntox -m test-trav\n\n# A single test file against core\ntox -e py-cov -- core/tests/path/to/test_file.py\n\n# A single test file against Travertino\ntox -e py-trav -- travertino/tests/path/to/test_file.py\n\n# Towncrier draft (preview assembled release notes)\ntox -e towncrier-check\n\n# Docs lint\ntox -e docs-lint\n```\n\n### Testbed (backend validation)\n\nThe core suite uses the Dummy backend. Real backend behaviour is validated through the testbed app. Install only the backend under test in your virtualenv, then:\n\n```console\n# Desktop (from testbed/)\nbriefcase dev --app testbed --test\n\n# GTK variants (Linux)\nbriefcase dev --app testbed --test\nTOGA_GTK=4 TOGA_GTKLIB=None briefcase dev --app testbed --test\nTOGA_GTK=4 TOGA_GTKLIB=Adw briefcase dev --app testbed --test\n\n# Qt (Linux)\nbriefcase dev --app testbed-qt --test\n\n# Textual (Linux)\nbriefcase dev --app testbed-textual --test\n\n# Mobile (requires the relevant SDK/toolchain)\nbriefcase run android --app testbed --test\nbriefcase run iOS --app testbed --test   # macOS host only\n\n# Subset with slow mode for visual inspection\nbriefcase dev --app testbed --test -- tests/widgets/test_button.py --slow\n```\n\n**Do not touch the keyboard/mouse while the testbed is running** — it drives input programmatically and will desync.\n\n## Change notes\n\nEvery user-visible PR needs a file in `changes/`:\n\n```text\nchanges/<issue_or_pr_number>.<kind>.md\n```\n\n`<kind>` MUST be one of: `feature`, `bugfix`, `removal`, `doc`, `misc`. Content is one or more sentences of past-tense prose describing the user-visible change. `misc` entries are hidden from release notes and appropriate for purely internal changes. Do not edit `docs/en/about/releases.md` directly; towncrier assembles it at release time.\n\n## Coding conventions\n\n- Follow the Toga code style guide linked from `CONTRIBUTING.md`. Ruff enforces most of it; do not disable rules locally.\n- Keep public API surface minimal and documented. New public names MUST appear in reference docs under `docs/en/reference/api/`.\n- Type hints: use them on public API; keep them consistent with the `.pyi` stub (`core/src/toga/__init__.pyi`) when applicable. That stub is excluded from Ruff — hand-edit it carefully.\n- `# pragma: no cover` is reserved for the cases already whitelisted in `tool.coverage.coverage_conditional_plugin.rules`. Do not introduce new ones to work around missing tests.\n- `filterwarnings = [\"error\"]` is set for pytest; warnings in tests are failures. Either fix the root cause or add a scoped, commented `pytest.warns(...)` / `filterwarnings` mark.\n- `isort` config in root `pyproject.toml` lists the first-party backend packages; add new packages there if you create one.\n\n## Documentation expectations\n\n- Every new public API, widget, or behavioural change MUST update `docs/en/` in the same PR.\n- Tutorials live under `docs/en/tutorial/`, how-tos under `docs/en/how-to/`, reference under `docs/en/reference/`, topic explanations under `docs/en/topics/`.\n- Build-time doc linting runs through `tox -e docs-lint`; fix anything it reports.\n- Markdown files in this project (including `AGENTS.md`, `docs/en/`, and `changes/` fragments) must **not** use hard line breaks to enforce an 80-character column limit. Each paragraph or list item must be written as a single unbroken line, regardless of its length. Let the reader's editor or renderer handle wrapping. This rule applies to all prose. Code blocks, directory trees, and other pre-formatted blocks are exempt — keep those readable within their own constraints. When writing or editing any `.md` file, do not insert newlines mid-sentence or mid-paragraph to stay within 80 columns.\n- Follow the BeeWare documentation style guide (linked from `CONTRIBUTING.md`).\n\n## Pull-request workflow\n\n1. Branch off `main` with a descriptive name. Do not push to `main`.\n2. Make the smallest change that addresses one issue. Avoid scope creep; file a separate issue/PR for drive-by refactors.\n3. Before opening the PR, run locally:\n    - `pre-commit run --all-files`\n    - `tox -m test` (expect 100% coverage)\n    - Testbed on any backend the change affects\n4. Include in the PR:\n    - A `changes/<issue>.<kind>.md` fragment\n    - Docs updates when user-visible\n    - A description naming the issue closed and the backends exercised\n5. CI MUST be green. Reviewers confirm the five constitutional principles; failures are fixed, not waived.\n6. Default merge strategy is squash; the squash message is what users will read, so make it describe the user-visible change.\n\n## Agent-specific rules\n\nAgents operating in this repo MUST:\n\n- Load `.specify/memory/constitution.md` before any change that affects public API, backends, test coverage, or release tooling.\n- Prefer editing existing files over creating new ones. Never proactively create new top-level files or directories.\n- Keep the `<!-- SPECKIT START --> ... <!-- SPECKIT END -->` block at the top of this file intact; SpecKit commands inject plan context there.\n- Never add `# pragma: no cover`, `# noqa`, or disable Ruff/codespell rules inline to pass CI; diagnose and fix the underlying issue.\n- Never commit secrets, API keys, `.env` files, or contributor PII.\n- Never rewrite Git history on `main` or force-push shared branches.\n- When uncertain about backend parity or API shape, open an issue or discussion before implementing; Toga favours design-first for anything non-trivial (see `docs/en/how-to/contribute/how/propose-feature.md`).\n- Disclose AI assistance in the PR description where it is material to review, per the BeeWare AI Policy.\n\n## Where to look next\n\n- `CONTRIBUTING.md` — entry point for all contributors.\n- `.specify/memory/constitution.md` — binding project principles.\n- `docs/en/how-to/contribute/` — style guides, PR process, review guide, scope-creep guide, AI policy.\n- `docs/en/reference/platforms/` — per-backend requirements and status.\n- Toga documentation site: <https://toga.beeware.org>\n- BeeWare community and Code of Conduct: <https://beeware.org>\n","category":"root","tokens":2516}]}