a11ydebt 0.1.0__tar.gz

a11ydebt-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+# Data is never committed. Rico's research-use terms forbid redistributing raw files;
+# data/raw/rico is a symlink to a local copy of Rico outside the repo.
+data/
+
+# Secrets
+*.env
+.env
+.env.*
+!.env.example
+kaggle.json
+access_token
+secrets/
+
+# Publishing gate: created by Obada only, never committed
+RELEASE_APPROVED
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+.coverage
+htmlcov/
+
+# OS and editors
+.DS_Store
+.idea/
+.vscode/

a11ydebt-0.1.0/CHANGELOG.md

@@ -0,0 +1,102 @@
+# Changelog
+
+All notable changes to this project are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
+[Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-10
+The first release. It audits Rico and AndroidControl and reproduces the corpus coverage numbers
+and cluster-bootstrap intervals of the IEEE AISSA 2026 paper exactly.
+
+### Added
+- Package skeleton: a uv project on Python 3.12 (supports >=3.10), hatchling build, pydantic,
+  and ruff and pytest for development. Apache-2.0 `LICENSE` and a `NOTICE` for the ported AISSA
+  codebook.
+- Project docs: `CLAUDE.md`, `docs/roadmap.md`, `docs/licenses.md`, `docs/session-log.md`.
+- `a11ydebt.taxonomy`: the AISSA 2026 codebook ported unchanged. It covers class-name roles,
+  needs_label, icon_like and the inclusion rule (visible-to-user and positive area). It also adds
+  the P01 `interactive_image` rule: an image-based node that is clickable or focusable.
+- `a11ydebt.rico`: the Rico view-hierarchy loader. It walks the tree pre-order (same order as the
+  AISSA parser), applies the codebook flags per node, and takes apps from `ui_details.csv`.
+- `a11ydebt.coverage`: `coverage()` and `audit_rico()`. They return counts and proportions per
+  screen, per app and for the corpus, for three populations, plus a needs_label split by role.
+  Parsing can run in parallel, and parse failures are recorded instead of stopping the run.
+- CLI: `a11ydebt audit rico PATH [--limit N] [--workers N] [--out DIR]`, which writes
+  `screens.csv`, `apps.csv` and `summary.json`.
+- `scripts/compare_aissa.py`: a dev-only exact comparison with the AISSA pipeline outputs.
+- Tests: three synthetic fixture screens (not derived from Rico), 51 tests in total.
+- S2, AndroidControl:
+  - `a11ydebt.counts`: one shared per-screen counting loop, stdlib only.
+  - `a11ydebt.tfrecord`: the pure-Python TFRecord and protobuf readers, ported from AISSA.
+  - `a11ydebt.androidcontrol`: episodes, screens per step, the codebook flags, and the episode app
+    from the dominant resource-id package.
+  - `a11ydebt.kaggle_outputs`: reads the Kaggle kernel's outputs.
+- CLI: `a11ydebt audit androidcontrol SHARD...` and `a11ydebt summarize androidcontrol DIR`.
+- `kaggle/androidcontrol_parse/`: a private CPU script kernel that downloads, verifies, parses and
+  deletes one shard at a time. It writes per-screen Parquet and candidate-node Parquet, checkpoints
+  each shard, resumes, and stops before Kaggle's 12-hour limit. It is built by `build_kernel.py`
+  with pinned pyarrow and a pinned image. Run 1 covers AISSA's shards 00000-00009 and run 2
+  covers 00010-00019.
+- `scripts/aissa_androidcontrol_reference.py` records the shards and episode ids AISSA used.
+  `scripts/compare_aissa.py androidcontrol` checks a run against AISSA.
+- pyarrow 26.0.1 is a dev dependency, for the kernel tests and the scripts.
+- S3, bootstrap and report:
+  - `a11ydebt.bootstrap`: the cluster bootstrap of pooled coverage, ported from AISSA's
+    ReviewerChecks (`cluster_bootstrap_rate`, `pct_ci`, the cluster rules), plus the Wilson
+    interval. Apps are clusters, and an AndroidControl episode with no app is its own cluster.
+    The defaults are 5,000 resamples and seed 20260908, both configurable. Resamples are drawn
+    in blocks, bit-identical to AISSA's loop.
+  - `a11ydebt.report` and the CLI `a11ydebt report [LABEL=]AUDIT_DIR ... [--out DIR]
+    [--n-resamples N] [--seed S] [--conf C]`. It writes `report.md`, `coverage.csv`, `roles.csv`
+    and `screens_with_debt.csv` (default `data/release/report/`). Coverage carries app-cluster
+    and screen-cluster 95% intervals, and each interval has its own seeded generator.
+  - `scripts/compare_aissa.py bootstrap` replays AISSA's shared-stream bootstrap and reproduces
+    all four published `clustered_coverage` intervals and both `clustered_gap` intervals exactly.
+  - `scripts/check_androidcontrol_all20.py`: sanity checks for the all-20-shard tables.
+  - `docs/reproduction-bootstrap.md`, and an all-20 section in
+    `docs/reproduction-androidcontrol.md`.
+- numpy (>=1.26) is now a runtime dependency, for the bootstrap.
+- S4, packaging and release prep:
+  - CI (`.github/workflows/ci.yml`) runs ruff check, ruff format --check and pytest with coverage
+    on Python 3.10 to 3.13, mirroring reliacode. pytest-cov is a dev dependency.
+  - Package metadata: version 0.1.0, read from `a11ydebt/__init__.py`, plus keywords,
+    classifiers and project URLs. The sdist holds src, tests, the Kaggle kernel and the top-level
+    docs.
+  - `CITATION.cff` (validated with cffconvert 2.0.0) is the software entry, with the AISSA 2026
+    paper as preferred-citation. `.zenodo.json` holds the Zenodo archive metadata. The paper DOI
+    is a marked, commented placeholder until IEEE Xplore assigns it.
+    `tests/test_release_metadata.py` keeps their versions in step.
+  - `results/v0.1/`: the aggregate report tables for Rico, AndroidControl 10 shards and
+    AndroidControl all 20 shards (a robustness extension, not in the paper).
+  - Docs: `docs/data-card.md`, `docs/how-to-audit.md` (a two-page handout),
+    `docs/release-checklist.md`, and `docs/assets/qr-a11ydebt.png` (made with segno through uvx).
+  - `report.md` ends with a footnote on independent seeds (decision D1).
+- Release:
+  - `.github/workflows/publish.yml` uploads to PyPI through trusted publishing (no token) when a
+    GitHub release is published. The upload waits for the maintainer's approval in the `pypi`
+    environment, the build checks that the tag matches the package version, and every action is
+    pinned to a full commit SHA.
+
+### Fixed
+- `CorpusCoverage.n_apps` no longer counts screens without an identified app as an app.
+- The Kaggle job's `run_summary.json` counts distinct apps across shards instead of summing
+  per-shard counts.
+
+### Changed
+- The README is rewritten for first-time visitors: install, quickstarts, the results table, how
+  to cite, provenance, and the AI-use disclosure.
+- `tests/test_bootstrap.py`: the Wilson zero-bound test allows for libm rounding (Linux gives
+  about 3e-17).
+- `coverage()` and `screen_coverage()` accept any screen that follows `counts.ScreenLike`, so they
+  work for both corpora. `POPULATIONS` moved to `a11ydebt.counts` and is re-exported from
+  `a11ydebt.rico`.
+- `scripts/compare_aissa.py` takes a corpus subcommand (`rico` or `androidcontrol`). The old
+  two-argument Rico form still works.
+- Before going public: `CLAUDE.md` keeps only the project's own rules, `docs/roadmap.md` is a
+  public software roadmap, and the README's AI-use disclosure says the author directs the work,
+  reviews the changes and is responsible for the code. It also points to `prompts/` and
+  `reports/`, the record of the AI-assisted development.
+- `docs/release-checklist.md` uses the trusted-publishing workflow and attaches no files to the
+  GitHub release.

a11ydebt-0.1.0/CITATION.cff

@@ -0,0 +1,46 @@
+cff-version: 1.2.0
+message: "If you use a11ydebt, please cite the AISSA 2026 paper (preferred-citation below) and the software."
+type: software
+title: "a11ydebt: Audit Accessibility Debt in GUI-Agent Corpora"
+abstract: >-
+  a11ydebt measures content-description coverage, the share of UI elements that need a
+  screen-reader label and have one, in the GUI corpora behind computer-use agents. It reports
+  coverage per screen, per app and per corpus, with app-cluster bootstrap intervals. Version
+  0.1.0 audits Rico and AndroidControl, and it reproduces the corpus coverage numbers and
+  intervals of the IEEE AISSA 2026 paper exactly.
+authors:
+  - family-names: Kraishan
+    given-names: Obada
+    affiliation: "College of Media and Communication, Texas Tech University"
+version: "0.1.0"
+# PLACEHOLDER (software DOI): add the Zenodo DOI after the v0.1.0 release, then uncomment:
+# doi: "10.5281/zenodo.<record-id>"
+date-released: "2026-11-10"
+license: Apache-2.0
+repository-code: "https://github.com/obadaKraishan/a11ydebt"
+url: "https://github.com/obadaKraishan/a11ydebt"
+keywords:
+  - accessibility
+  - GUI agents
+  - computer-use agents
+  - datasets
+  - audit
+  - content descriptions
+  - Rico
+  - AndroidControl
+preferred-citation:
+  type: conference-paper
+  title: "Trained on What Screen Readers Cannot Read: Accessibility Debt in the GUI Corpora Behind Computer-Use Agents"
+  authors:
+    - family-names: Kraishan
+      given-names: Obada
+      affiliation: "College of Media and Communication, Texas Tech University"
+    - family-names: Jitkajornwanich
+      given-names: Kulsawasd
+      affiliation: "College of Media and Communication, Texas Tech University"
+  collection-title: "IEEE AISSA 2026"
+  conference:
+    name: "IEEE AISSA 2026"
+  year: 2026
+  # PLACEHOLDER (paper DOI): add the IEEE Xplore DOI when it is assigned, then uncomment:
+  # doi: "10.1109/<assigned-by-ieee>"

a11ydebt-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+

a11ydebt-0.1.0/NOTICE

@@ -0,0 +1,47 @@
+a11ydebt
+Copyright 2026 Obada Kraishan
+
+This product is licensed under the Apache License, Version 2.0 (see LICENSE).
+
+It includes code ported from accessibility-debt-agents, the analysis pipeline behind
+"Trained on What Screen Readers Cannot Read: Accessibility Debt in the GUI Corpora Behind
+Computer-Use Agents" (Kraishan and Jitkajornwanich, IEEE AISSA 2026):
+https://github.com/obadaKraishan/accessibility-debt-agents
+(commit 97c0378; the codebook is byte-identical in the camera-ready snapshot 567e030).
+
+  Ported files:
+  - src/a11ydebt/taxonomy.py: element roles, label status and the inclusion rule
+    (from src/a11ydebt/taxonomy.py)
+  - src/a11ydebt/tfrecord.py: the pure-Python TFRecord, tf.train.Example and
+    AndroidAccessibilityForest readers, and click resolution (from src/a11ydebt/tfrecord.py)
+  - src/a11ydebt/androidcontrol.py: the AndroidControl episode parse logic and the episode-app
+    rule (from phase2_processing/02_parse_androidcontrol.py and src/a11ydebt/apps.py, with the
+    platform-package list from config.yaml)
+  - src/a11ydebt/bootstrap.py: the cluster bootstrap of a pooled rate and its percentile
+    interval, and the cluster rules (from cluster_bootstrap_rate, pct_ci and Check 1 of
+    phase4_validation/03_reviewer_checks.py), the Wilson interval (from src/a11ydebt/stats.py),
+    and the seed and resample count (from config.yaml). AISSA's own src/a11ydebt/bootstrap.py
+    is an import shim and was not ported.
+
+That code was released under the MIT License:
+
+  Copyright (c) 2026 Obada Kraishan
+
+  Permission is hereby granted, free of charge, to any person obtaining a copy of this
+  software and associated documentation files (the "Software"), to deal in the Software
+  without restriction, including without limitation the rights to use, copy, modify, merge,
+  publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons
+  to whom the Software is furnished to do so, subject to the following conditions:
+
+  The above copyright notice and this permission notice shall be included in all copies or
+  substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+  INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
+  PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE
+  FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+  OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+  DEALINGS IN THE SOFTWARE.
+
+The datasets a11ydebt reads (Rico, AndroidControl, RICO-Semantics) carry their own terms and
+are not distributed with this software. See docs/licenses.md.

a11ydebt-0.1.0/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.5
+Name: a11ydebt
+Version: 0.1.0
+Summary: Audit accessibility debt (missing content descriptions) in the GUI corpora that train computer-use agents.
+Project-URL: Homepage, https://github.com/obadaKraishan/a11ydebt
+Project-URL: Repository, https://github.com/obadaKraishan/a11ydebt
+Project-URL: Issues, https://github.com/obadaKraishan/a11ydebt/issues
+Project-URL: Documentation, https://github.com/obadaKraishan/a11ydebt#readme
+Project-URL: Changelog, https://github.com/obadaKraishan/a11ydebt/blob/main/CHANGELOG.md
+Author: Obada Kraishan
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: accessibility,androidcontrol,audit,computer-use-agents,content-description,datasets,gui-agents,rico
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.26
+Requires-Dist: pydantic>=2.6
+Description-Content-Type: text/markdown
+
+# a11ydebt
+
+[![CI](https://github.com/obadaKraishan/a11ydebt/actions/workflows/ci.yml/badge.svg)](https://github.com/obadaKraishan/a11ydebt/actions/workflows/ci.yml)
+
+**Measure the accessibility debt in the GUI corpora behind computer-use agents.** Agents that
+operate phones learn from large corpora of recorded screens. A screen reader can only announce a
+button or an icon if the app gave it a label (an Android `content-desc`), and many apps don't.
+a11ydebt counts, for every element that needs a label, whether it has one. It reports the
+coverage per screen, per app and per corpus, with app-level cluster-bootstrap confidence
+intervals. It is the reproducible tool behind the IEEE AISSA 2026 paper *Trained on What Screen
+Readers Cannot Read: Accessibility Debt in the GUI Corpora Behind Computer-Use Agents*
+(Kraishan and Jitkajornwanich). From the raw data, it reproduces the paper's corpus coverage
+numbers (overall and by role) and its cluster-bootstrap intervals exactly.
+
+> Version 0.1.0, released on 2026-11-10. It supports Rico and AndroidControl, and needs Python
+> 3.10 or later.
+
+## Install
+From PyPI:
+```bash
+uv tool install a11ydebt
+# or
+pipx install a11ydebt
+```
+For the latest development version, install from GitHub instead:
+`uv tool install "git+https://github.com/obadaKraishan/a11ydebt.git"`.
+
+The runtime dependencies are pydantic and numpy. `a11ydebt summarize`, which reads the Kaggle
+kernel's Parquet outputs, also needs pyarrow: `pipx inject a11ydebt pyarrow`, or
+`uv tool install --with pyarrow ...`.
+
+## Quickstart: Rico
+1. Download Rico from <https://interactionmining.org/rico>, under its research-use terms. You
+   need *UI Screenshots and View Hierarchies* (`unique_uis.tar.gz`, 6.5 GB) and the UI metadata
+   file `ui_details.csv`. Unpack the archive (about 16 GB) to get `combined/*.json`, and put
+   `ui_details.csv` next to `combined/`. The checksums are in
+   [docs/reproduction-rico.md](docs/reproduction-rico.md).
+2. Audit and report:
+   ```bash
+   a11ydebt audit rico path/to/rico --workers 8 --out audit_rico   # about 6 minutes on 8 cores
+   a11ydebt report "Rico=audit_rico" --out report
+   ```
+   `audit` writes `screens.csv`, `apps.csv` and `summary.json`. `report` writes `report.md`,
+   `coverage.csv`, `roles.csv` and `screens_with_debt.csv`.
+
+## Quickstart: AndroidControl
+AndroidControl (Apache-2.0) is 20 GZIP TFRecord shards, about 50 GB in all, at
+`https://storage.googleapis.com/gresearch/android_control/`.
+
+- **One shard, locally (2.5 GB):**
+  ```bash
+  curl -O https://storage.googleapis.com/gresearch/android_control/android_control-00000-of-00020
+  curl -O https://storage.googleapis.com/gresearch/android_control/splits.json
+  a11ydebt audit androidcontrol android_control-00000-of-00020 --splits splits.json --out audit_ac
+  ```
+- **The full corpus, on a free Kaggle CPU kernel** (from a clone of this repo, with the Kaggle CLI
+  set up). First set `kernel_id` in `kaggle/androidcontrol_parse/config_run1.json` to
+  `<your-kaggle-username>/a11ydebt-androidcontrol-run1`. The kernel downloads, verifies, parses and
+  deletes one shard at a time, and returns about 12 MB of Parquet per 10 shards
+  ([kaggle/androidcontrol_parse/README.md](kaggle/androidcontrol_parse/README.md)).
+  ```bash
+  uv run python kaggle/androidcontrol_parse/build_kernel.py kaggle/androidcontrol_parse/config_run1.json
+  kaggle kernels push -p kaggle/androidcontrol_parse/build/run1
+  kaggle kernels output <your-kaggle-username>/a11ydebt-androidcontrol-run1 -p kaggle_out/run1
+  a11ydebt summarize androidcontrol kaggle_out --out audit_ac
+  a11ydebt report "Rico=audit_rico" "AndroidControl=audit_ac" --out report
+  ```
+  `config_run1.json` covers shards 00000 to 00009 (the paper's 10), and `config_run2.json` covers
+  00010 to 00019.
+
+## What it counts
+Every count applies the AISSA 2026 codebook (`src/a11ydebt/taxonomy.py`). Roles come from
+class names, and only nodes that are visible to the user and have positive area are included.
+
+| Population | Definition |
+|---|---|
+| `needs_label` (the paper's primary measure) | Images, plus interactive elements with no visible text. Containers and web views are exempt. |
+| `icon_like` (the paper's strictest measure) | A tappable image or button with no visible text. |
+| `interactive_image` (new in a11ydebt) | An image-based node (ImageView family, ImageButton, FAB) that is clickable or focusable. |
+
+## Results (v0.1.0)
+Label coverage, with 95% app-cluster bootstrap intervals[^seeds]. AndroidControl is the
+paper's 10 shards. Full tables: [results/v0.1/](results/v0.1/).
+
+| Population | Rico: candidates | Rico: coverage % [95% CI] | AndroidControl: candidates | AndroidControl: coverage % [95% CI] |
+|---|---:|---:|---:|---:|
+| needs_label | 502,585 | **17.74** [17.12, 18.37] | 1,462,544 | **57.27** [55.66, 58.84] |
+| icon_like | 127,552 | **33.20** [31.96, 34.47] | 194,529 | **62.75** [57.76, 67.39] |
+| interactive_image | 105,780 | 33.29 [31.97, 34.66] | 133,266 | 58.88 [53.50, 64.15] |
+
+Rico has 66,261 screens from 9,384 apps. The AndroidControl sample has 49,892 screens from 7,623
+episodes, with 951 app clusters (700 apps, plus 251 episodes with no identified app, each its own
+cluster). The point estimates equal the paper's exactly. The interactive_image row is not in the
+paper.
+
+[^seeds]: Intervals use independent seeds. The paper's shared-stream intervals (Table I) are
+    reproduced exactly by `scripts/compare_aissa.py bootstrap`; see
+    [docs/reproduction-bootstrap.md](docs/reproduction-bootstrap.md).
+
+## Reproducing the paper
+- Rico: [docs/reproduction-rico.md](docs/reproduction-rico.md). All 66,261 screens and 9,384 apps
+  equal the AISSA pipeline's counts.
+- AndroidControl: [docs/reproduction-androidcontrol.md](docs/reproduction-androidcontrol.md). All
+  10 shards, 7,623 episodes and 49,888 non-empty screens are equal.
+- Intervals: [docs/reproduction-bootstrap.md](docs/reproduction-bootstrap.md). All six published
+  cluster-bootstrap intervals match, with bit-identical draws.
+- A practical guide: [docs/how-to-audit.md](docs/how-to-audit.md).
+
+`scripts/compare_aissa.py` checks a run against copies of the AISSA pipeline's outputs. It is a
+development tool and is not part of the package.
+
+## Data
+a11ydebt ships **no data**. Rico's terms forbid redistributing its files, so this repository
+publishes only aggregate statistics. AndroidControl is Apache-2.0. See
+[docs/data-card.md](docs/data-card.md) for what the tables contain and how to regenerate them, and
+[docs/licenses.md](docs/licenses.md) for each dataset's terms.
+
+## How to cite
+Please cite the paper. If you use the software, cite it as well. [CITATION.cff](CITATION.cff)
+carries both entries.
+
+```bibtex
+@inproceedings{kraishan2026trained,
+  title     = {Trained on What Screen Readers Cannot Read: Accessibility Debt in the {GUI}
+               Corpora Behind Computer-Use Agents},
+  author    = {Kraishan, Obada and Jitkajornwanich, Kulsawasd},
+  booktitle = {IEEE AISSA 2026},
+  year      = {2026},
+  note      = {DOI to be added when IEEE Xplore assigns one}
+}
+
+@software{kraishan2026a11ydebt,
+  author  = {Kraishan, Obada},
+  title   = {a11ydebt: Audit Accessibility Debt in GUI-Agent Corpora},
+  version = {0.1.0},
+  year    = {2026},
+  url     = {https://github.com/obadaKraishan/a11ydebt},
+  note    = {Zenodo DOI to be added at release}
+}
+```
+
+## Development
+```bash
+uv sync                                          # Python 3.10+, with ruff, pytest and pyarrow for dev
+uv run pytest                                    # synthetic fixtures only, no data needed
+uv run ruff check . && uv run ruff format --check .
+```
+CI runs the same checks on Python 3.10 to 3.13.
+
+## License and provenance
+The code is Apache-2.0 ([LICENSE](LICENSE)). The codebook, the AndroidControl reader and the
+cluster bootstrap are ported from the MIT-licensed AISSA pipeline (accessibility-debt-agents).
+[NOTICE](NOTICE) lists every ported file and keeps the MIT notice. The datasets have their own
+terms ([docs/licenses.md](docs/licenses.md)).
+
+## AI-use disclosure
+a11ydebt is developed with [Claude Code](https://claude.com/claude-code), an AI coding assistant.
+The author directs the work, reviews the changes, and is responsible for the code and its
+correctness. Commits made with Claude Code carry a `Co-Authored-By: Claude` trailer, so the
+history shows which changes were AI-assisted. No language model produces any number in the
+audit: the counts come from deterministic parsing, and the intervals from a seeded bootstrap.
+
+The [prompts/](prompts/) and [reports/](reports/) folders hold the session-by-session record of
+the AI-assisted development.