openansho 0.1.0__tar.gz

openansho-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+.venv/
+*.egg-info/
+build/
+dist/
+*.spec
+*.sqlite
+*.sqlite3
+planning
+\#planning\#
+.openansho_user

openansho-0.1.0/CLAUDE.md

@@ -0,0 +1,83 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+OpenAnsho is a desktop app (PySide6/Qt) for qualitative data analysis: importing text documents, tagging ("coding") spans of text with a hierarchical codebook, and exporting/reporting on the coded segments. Projects are single `.sqlite` files.
+
+## Development setup
+
+First-time setup, run once from the repo root:
+
+```bash
+python3 -m venv .venv           # create the project virtualenv
+source .venv/bin/activate       # activate it
+pip install -e ".[dev]"        # install package + dev deps (pytest, pytest-qt)
+```
+
+Every subsequent session, activate the virtualenv before running any commands below:
+
+```bash
+source .venv/bin/activate       # activate the project virtualenv
+```
+
+To run the development version of the app (with the virtualenv active):
+
+```bash
+python -m openansho              # run the app (or the `openansho` console script)
+```
+
+## Commands
+
+The project uses a `.venv` virtualenv at the repo root — activate it before running any of the commands below.
+
+```bash
+source .venv/bin/activate       # activate the project virtualenv
+pip install -e ".[dev]"        # install package + dev deps (pytest, pytest-qt)
+python -m openansho             # run the app (or the `openansho` console script)
+pytest                          # run the full test suite
+pytest tests/test_db.py::test_create_code_and_list_codes   # run a single test
+make dist                       # build the PyPI sdist + wheel into dist/pypi
+```
+
+There is no configured linter/formatter/type-checker in `pyproject.toml` — don't assume `ruff`/`black`/`mypy` are wired in.
+
+**Known hang: the full suite in Claude Code's sandbox.** Running the unscoped suite (bare `pytest`, or `pytest tests/`) reliably hangs in Claude Code's sandboxed/offscreen environment — the process gets stuck in an uninterruptible sleep that not even `kill -9` can clear, apparently a Qt/native-windowing issue with `tests/test_always_selected_code.py` specifically when it runs alongside the rest of the suite (it passes in well under a second in isolation, e.g. `pytest tests/test_always_selected_code.py`). `pytest tests/ --ignore=tests/test_always_selected_code.py` runs the rest of the suite (142 tests) in about a second. Claude Code should scope test runs (a single file, `--ignore` that file, or `-k`) rather than invoking the bare full suite. The human developer should still run the full suite occasionally outside this sandbox (a normal local terminal), since that's the only way to catch a regression in the one file this workaround always excludes.
+
+## Distribution
+
+The app ships through two channels, and a change to how the app finds its files has to work in both:
+
+- **Prebuilt executables** via PyInstaller (`make build-mac`/`build-windows`/`build-linux`, published to the `builds` branch by `.github/workflows/ci.yml`).
+- **A PyPI sdist + wheel** (`make dist`, published by `.github/workflows/release.yml` on a `v*` tag via trusted publishing; `make publish` is the manual fallback). Releasing means bumping `__version__` in `src/openansho/__init__.py` — hatchling reads the version from there, so `pyproject.toml` has none of its own — then pushing a matching tag, which the workflow verifies against `__version__` before uploading.
+
+Consequences worth knowing before touching the packaging:
+
+- **`__main__._icon_path` has three branches** because the icon lives in a different place in each layout: `sys._MEIPASS/images/` in a PyInstaller bundle, next to the package in an installed wheel (pyproject `force-include`s `images/kanji_shou_app_icon.png` into `openansho/`, since a wheel has no repo root), and `images/` at the repo root when running from source. Package data added in the future needs the same treatment — `tutorial.txt` avoids it by living inside the package to begin with, which is the simpler option.
+- **`user.username_file` picks a directory based on how the app was installed.** Frozen builds and source checkouts own their directory, so the `.openansho_user` sidecar sits next to the app as before; a pip install would otherwise write into site-packages, which can be read-only and is replaced wholesale on upgrade, so `user.installed_in_site_packages()` routes it to `user.config_directory()` instead.
+- **The entry point is a `gui-script`, not a `console script`**, so the Windows launcher is built against `pythonw` and doesn't leave a console window behind the app. `python -m openansho` is the console-attached form to recommend when someone needs a traceback.
+- `tests/test_packaging.py` covers the layout-dependent paths; `tests/conftest.py` pins `installed_in_site_packages` off so the suite never touches a real config directory.
+
+## Architecture
+
+**Layering:** `db.py` → `reporting.py`/`text_extract.py`/`tutorial.py` → `ui/*`. The non-UI modules have zero Qt imports and operate directly on a `sqlite3.Connection`, so they're usable from tests (or a future CLI) without spinning up a `QApplication`.
+
+- **`db.py`** — the only place that touches SQL. Three tables: `documents`, `codes` (self-referencing via `parent_id`, `ON DELETE CASCADE`), `segments` (document + code + `start_offset`/`end_offset` char range + optional memo). Note `delete_code` re-parents a deleted code's children to its own parent *before* deleting, specifically to dodge the cascade that would otherwise wipe out the whole subtree.
+- **`reporting.py`** — read-only aggregation/export over `db.py` (CSV/JSON segment export, code-frequency counts). `code_path()` builds the "Parent > Child" breadcrumb by walking `parent_id` up to the root.
+- **`text_extract.py`** — `read_document_text(path)` turns a file into the plain text that gets stored in `documents.content`, dispatching on extension: `.docx` goes through a hand-rolled `zipfile`+`ElementTree` reader (no `python-docx`, so the packaged app keeps PySide6 as its only dependency), anything else is read as UTF-8. Failures raise `DocumentReadError` whose message is shown verbatim in the import dialog.
+- **`tutorial.py`** — the built-in tutorial project the app opens at startup (`__main__.main` calls `MainWindow.open_tutorial_project`, also reachable via File > Open Tutorial). `open_tutorial_project()` returns a `db.connect(":memory:")` connection seeded with `tutorial.txt`, which ships as package data next to the module — the in-memory database is the whole mechanism for "the tutorial codebook is never saved," so don't give it a file path. `MainWindow._set_connection` accepts `path=None` for exactly this project: no file to title the window after and nothing to put in Open Recent.
+- **`ui/main_window.py`** — the app. `MainWindow` methods split into two groups by convention: `_on_*` slots that own dialog/QMessageBox interaction, and plain methods (`create_project`, `import_document`, `add_code`, `apply_segment`, `delete_code`, ...) that contain the actual logic and take/return plain values. Tests drive the app through the latter, never through the `_on_*` slots or real file dialogs.
+- **`ui/vim_viewer.py`** — `VimTextViewer`, a read-only `QPlainTextEdit` with hand-rolled vim motions (`hjkl`, `w/b/e` vs `W/B/E` WORD variants, `0/$`, `gg/G`, viewport-relative `H/L`, visual mode via `v`). It disables the native blinking cursor (`setCursorWidth(0)`) and instead renders its own block-cursor highlight as an `ExtraSelection`, layered alongside the per-code highlight selections from `MainWindow`.
+- **`ui/code_tree.py`** — `CodeTreeWidget`, adds internal drag-and-drop re-parenting on top of `QTreeWidget`, emitting `codeReparented(code_id, new_parent_id)` for `MainWindow` to persist (and validate — no self-parenting, no moving under one's own descendant).
+- **`ui/code_filter_input.py`** — `CodeFilterLineEdit`, a `QLineEdit` that repurposes Up/Down to cycle the currently-matched code instead of moving the text cursor.
+- **`ui/report_dialog.py`** — plain read-only table dialog for the code-frequency report.
+- **`ui/font_scale.py`** — application-wide font scaling, expressed as a percentage of the platform's default UI font. Scaling has to be applied *twice* to actually take effect: `apply_font_scale` sets `QApplication`'s font (what later-created dialogs/menus start from), and `font_scale_style` returns a `QWidget { font-size: … }` fragment that `MainWindow._apply_theme` appends to the theme stylesheet — setting any stylesheet makes Qt give each polished widget an explicit font, which then stops tracking `QApplication`'s, so already-built panes only resize via the stylesheet. Note Qt's QSS parser silently rejects fractional point sizes, hence the rounding in `scaled_font`.
+
+**Cross-pane keyboard model:** `MainWindow` installs a `QApplication`-wide `eventFilter` (not per-widget handlers) so a handful of shortcuts work regardless of which pane has focus: Space jumps focus to the code filter, Up/Down cycle the matched/highlighted code when the viewer has a selection, Enter applies the current code to the viewer's selection, and `x` deletes segments touching the cursor (normal mode) or the current selection (visual mode). When adding a new global shortcut, it goes here, not on an individual widget.
+
+**Focus styling:** panes are visually highlighted on focus via a Qt dynamic property (`"focused"`) toggled from `QApplication.focusChanged`, matched by the QSS in `PANE_FOCUS_STYLE` — not via per-widget `focusInEvent` overrides.
+
+**Coding workflow invariant:** applying a code always goes through `MainWindow.apply_segment`, which both writes the segment (`db.create_segment`) and refreshes the code tree/highlights/segment list in one place — don't call `db.create_segment` directly from UI code.
+
+**Keyboard shortcuts must stay documented.** `ui/shortcuts_dialog.py`'s `SHORTCUT_SECTIONS` is shown to the user via the `?` popup and is the single source of truth for "what keys does this app respond to." Any time a keyboard shortcut is added, changed, or removed anywhere in the UI (the global `eventFilter` in `main_window.py`, vim motions in `vim_viewer.py`, `code_filter_input.py`, `code_tree.py`, or any `QShortcut`/menu accelerator), update `SHORTCUT_SECTIONS` in the same change so the popup never drifts out of sync with actual behavior.

openansho-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zachary del Rosario
+
+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.

openansho-0.1.0/Makefile

@@ -0,0 +1,171 @@
+# Makefile for building the OpenAnsho desktop app with PyInstaller.
+#
+# PyInstaller does not cross-compile: it can only build an executable for
+# the OS it runs on. So build-mac must run on macOS, build-windows on
+# Windows, and build-linux on Linux (e.g. as separate jobs in a CI matrix).
+# `make build` builds for whichever platform you're currently on.
+
+APP_NAME := OpenAnsho
+ENTRY_POINT := src/openansho/__main__.py
+ICON := images/kanji_shou_app_icon.png
+TUTORIAL := src/openansho/tutorial.txt
+DIST_DIR := dist
+BUILD_DIR := build
+VENV := .venv
+
+# --add-data uses a platform-specific separator between source and destination.
+ifeq ($(OS),Windows_NT)
+    VENV_BIN := $(VENV)/Scripts
+    SYSTEM_PYTHON := python
+    ADD_DATA := $(ICON);images
+    ADD_TUTORIAL := $(TUTORIAL);openansho
+else
+    VENV_BIN := $(VENV)/bin
+    SYSTEM_PYTHON := python3
+    ADD_DATA := $(ICON):images
+    ADD_TUTORIAL := $(TUTORIAL):openansho
+endif
+
+PYTHON := $(VENV_BIN)/python
+PIP := $(VENV_BIN)/pip
+PYINSTALLER := $(VENV_BIN)/pyinstaller
+PYTEST := $(VENV_BIN)/pytest
+
+PYPI_DIR := $(DIST_DIR)/pypi
+
+.PHONY: help venv install install-build install-publish test clean build build-mac build-windows build-linux dist publish publish-test
+
+help:
+	@echo "Targets:"
+	@echo "  venv           Create the virtualenv at $(VENV)"
+	@echo "  install        Install the package with dev dependencies"
+	@echo "  install-build  Install PyInstaller into the virtualenv"
+	@echo "  test           Run the full test suite"
+	@echo "  build-mac      Build a macOS .app bundle (must run on macOS)"
+	@echo "  build-windows  Build a Windows .exe (must run on Windows)"
+	@echo "  build-linux    Build a Linux binary (must run on Linux)"
+	@echo "  build          Build for the current platform"
+	@echo "  dist           Build the PyPI sdist + wheel into $(PYPI_DIR)"
+	@echo "  publish-test   Upload the sdist + wheel to TestPyPI"
+	@echo "  publish        Upload the sdist + wheel to PyPI"
+	@echo "  clean          Remove build/dist artifacts and .spec files"
+
+$(VENV_BIN)/python:
+	$(SYSTEM_PYTHON) -m venv $(VENV)
+
+venv: $(VENV_BIN)/python
+
+install: venv
+	$(PIP) install -e ".[dev]"
+
+install-build: venv
+	$(PIP) install -e ".[build]"
+
+install-publish: venv
+	$(PIP) install -e ".[publish]"
+
+# Note: the full suite is known to hang in Claude Code's sandboxed/offscreen
+# environment (see CLAUDE.md) — this target is meant for a real terminal or CI.
+test: install
+	$(PYTEST)
+
+clean:
+	rm -rf $(BUILD_DIR) $(DIST_DIR) *.spec
+
+# --- Platform builds --------------------------------------------------------
+#
+# Windows and Linux build with --onefile, which bundles the interpreter, Qt,
+# and the app into a single self-contained executable. PyInstaller's default
+# one-dir mode instead emits the executable next to an _internal/ folder
+# holding the interpreter library (python311.dll / libpython3.11.so), which the
+# launcher resolves relative to its own location — so the moment someone
+# downloads or copies just the executable (e.g. grabbing the single file off
+# the `builds` branch, where GitHub only offers per-file downloads), it dies
+# with "Failed to load Python DLL ...\_internal\python311.dll" or the Linux
+# equivalent. A single file has no such loose ends. Costs a few seconds of
+# startup while it unpacks to a temp dir.
+#
+# macOS stays one-dir, since --windowed there wraps the result in a .app bundle
+# and a bundle is a directory by definition.
+#
+# Both Linux and macOS ship their result as a tarball (see build-linux for the
+# full reasoning). The short version: the artifact pipeline mangles anything it
+# ships loose. actions/upload-artifact zips without preserving Unix modes, and
+# an HTTP download carries no permission metadata at all, so the executable bit
+# is gone by the time a user has the file. macOS additionally needs the archive
+# because upload-artifact follows symlinks: it dereferences every
+# Versions/Current -> Versions/A link inside the Qt frameworks into a second
+# full copy, which both doubles the size and invalidates the _CodeSignature
+# manifest that describes the symlinked layout. tar records modes and symlinks
+# inside the archive, so all of it survives however the archive travelled.
+
+build-mac: install-build
+	$(PYINSTALLER) --name "$(APP_NAME)" --windowed --noconfirm --clean \
+		--icon $(ICON) --add-data "$(ADD_DATA)" --add-data "$(ADD_TUTORIAL)" \
+		--distpath $(DIST_DIR)/mac --workpath $(BUILD_DIR)/mac \
+		$(ENTRY_POINT)
+	chmod +x "$(DIST_DIR)/mac/$(APP_NAME).app/Contents/MacOS/$(APP_NAME)"
+	COPYFILE_DISABLE=1 tar -czf $(DIST_DIR)/mac/$(APP_NAME)-mac.tar.gz \
+		-C $(DIST_DIR)/mac "$(APP_NAME).app"
+	rm -rf "$(DIST_DIR)/mac/$(APP_NAME).app" $(DIST_DIR)/mac/$(APP_NAME)
+
+build-windows: install-build
+	$(PYINSTALLER) --name "$(APP_NAME)" --windowed --onefile --noconfirm --clean \
+		--icon $(ICON) --add-data "$(ADD_DATA)" --add-data "$(ADD_TUTORIAL)" \
+		--distpath $(DIST_DIR)/windows --workpath $(BUILD_DIR)/windows \
+		$(ENTRY_POINT)
+
+# The Linux binary ships as a tarball rather than a bare ELF file, because the
+# executable bit does not survive the trip to a user's machine otherwise. Two
+# separate things strip it: actions/upload-artifact zips without preserving Unix
+# modes (so the `builds` branch ends up with 100644 blobs), and an HTTP download
+# carries no permission metadata at all, so even a 100755 blob lands as 644 when
+# fetched through GitHub's "Download raw file". A non-executable ELF doesn't run
+# — GNOME Files reports "There is no app installed for Executable files" instead
+# of launching it. tar records the mode inside the archive, so extracting yields
+# a binary that is executable no matter how the archive travelled.
+#
+# Only the tarball is left in the dist directory: shipping the loose binary
+# alongside it would just be a broken file for people to download by mistake.
+build-linux: install-build
+	$(PYINSTALLER) --name "$(APP_NAME)" --onefile --noconfirm --clean \
+		--add-data "$(ADD_DATA)" --add-data "$(ADD_TUTORIAL)" \
+		--distpath $(DIST_DIR)/linux --workpath $(BUILD_DIR)/linux \
+		$(ENTRY_POINT)
+	chmod +x $(DIST_DIR)/linux/$(APP_NAME)
+	tar -czf $(DIST_DIR)/linux/$(APP_NAME)-linux.tar.gz \
+		-C $(DIST_DIR)/linux $(APP_NAME)
+	rm $(DIST_DIR)/linux/$(APP_NAME)
+
+# --- PyPI distribution ------------------------------------------------------
+#
+# Unlike the PyInstaller builds above, the sdist and wheel are pure Python and
+# platform-independent, so one machine (or one CI job) produces the artifacts
+# everyone installs; PySide6 is left to pip to resolve per platform. The wheel
+# is built from the sdist so that anything missing from the sdist shows up here
+# rather than in a user's failed `pip install`.
+#
+# The release workflow (.github/workflows/release.yml) runs the same two steps
+# on a version tag and uploads via PyPI trusted publishing, so `make publish` is
+# only needed for a manual release — it prompts for a PyPI API token.
+
+dist: install-publish
+	rm -rf $(PYPI_DIR)
+	$(PYTHON) -m build --outdir $(PYPI_DIR)
+	$(VENV_BIN)/twine check --strict $(PYPI_DIR)/*
+
+publish-test: dist
+	$(VENV_BIN)/twine upload --repository testpypi $(PYPI_DIR)/*
+
+publish: dist
+	$(VENV_BIN)/twine upload $(PYPI_DIR)/*
+
+# Convenience: build for whatever OS `make` is currently running on.
+UNAME_S := $(shell uname -s 2>/dev/null)
+ifeq ($(OS),Windows_NT)
+build: build-windows
+else ifeq ($(UNAME_S),Darwin)
+build: build-mac
+else
+build: build-linux
+endif

openansho-0.1.0/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.5
+Name: openansho
+Version: 0.1.0
+Summary: Open-source qualitative data analysis
+Project-URL: Homepage, https://github.com/zdelrosario/open-ansho
+Project-URL: Repository, https://github.com/zdelrosario/open-ansho
+Project-URL: Issues, https://github.com/zdelrosario/open-ansho/issues
+Author-email: Zachary del Rosario <zdelrosario@olin.edu>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: codebook,coding,qda,qualitative-data-analysis,research,vim
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: MacOS X
+Classifier: Environment :: Win32 (MS Windows)
+Classifier: Environment :: X11 Applications :: Qt
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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 :: Information Analysis
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.9
+Requires-Dist: pyside6>=6.6
+Provides-Extra: build
+Requires-Dist: pillow; extra == 'build'
+Requires-Dist: pyinstaller>=6.0; extra == 'build'
+Provides-Extra: dev
+Requires-Dist: pytest-qt>=4.4; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: publish
+Requires-Dist: build>=1.2; extra == 'publish'
+Requires-Dist: twine>=6.1; extra == 'publish'
+Description-Content-Type: text/markdown
+
+# Open Ansho (暗証) - Open-source qualitative data analysis
+
+Open Ansho is a free and open-source desktop app for qualitative data analysis of text documents. This was designed as a fast and focused tool with the following goals:
+
+- Fast coding: By using Vim-inspired keybindings, you can code a document without ever moving your hands off the keyboard.
+- Easy collaboration: No signup needed. All data (text and codes) are written to a database file that you can store in a shared directory (e.g., Dropbox, Google Drive, OneDrive).
+- Clarity: Visually compare overlapping code segments through vertically-separated split highlights. Easily see simultaneous coding through striped segments.
+- Lightweight: No bloat. Just fast coding.
+
+Documents can be imported as plain text (`.txt`) or Microsoft Word (`.docx`) files; Word documents are converted to plain text on import, one line per paragraph.
+
+The app opens on a built-in tutorial that walks you through coding your first document, so there is nothing to set up before trying it. The tutorial is a scratch project held in memory — code it up however you like, then use File > New Project when you're ready to work on your own data. Nothing from the tutorial is saved, so it starts fresh every time you open the app (File > Open Tutorial brings it back mid-session).
+
+This software was created using Claude Code.
+
+## Download and Run
+
+Prebuilt executables for macOS, Windows, and Linux are published on the [`builds` branch](https://github.com/zdelrosario/open-ansho/tree/builds/runs). Each build lives in its own folder named `<run number>-<commit>`; open the highest-numbered one for the most recent build, then the folder for your operating system.
+
+The app is fully self-contained — there is nothing to install, and no Python needed. On Windows and Linux, expect a few seconds of delay every time you start it: those builds are a single file that unpacks itself to a temporary directory on each launch. The macOS app is a normal bundle and starts without that pause.
+
+These builds are not code-signed, so each operating system will warn you the first time you open one. The steps below include how to get past that. If you would rather not click through a security warning, run from source instead — see [Development Setup](#development-setup).
+
+> **Tip:** OpenAnsho remembers your username in a `.openansho_user` file it writes alongside the executable (inside the app bundle, on macOS). Put the app somewhere permanent and writable — `~/Applications` on macOS, a folder under your user account such as `C:\Users\<you>\Apps` on Windows — rather than leaving it in `Downloads`. Avoid `C:\Program Files`, which a standard account cannot write to. Replacing the app with a newer build starts you over with a fresh username file.
+
+### Windows
+
+1. Download `OpenAnsho.exe` from the `windows` folder.
+2. Double-click it.
+3. Windows SmartScreen will likely say it "protected your PC". Click **More info**, then **Run anyway**.
+
+### macOS
+
+1. Download `OpenAnsho-mac.tar.gz` from the `mac` folder.
+2. Double-click the archive to extract `OpenAnsho.app`, then drag it to your Applications folder.
+3. Double-click the app. macOS will refuse to open it, saying the developer cannot be verified.
+4. Open **System Settings → Privacy & Security**, scroll to the Security section, and click **Open Anyway** next to the message about OpenAnsho. Confirm once more when prompted.
+
+You only need to do step 4 once. On older versions of macOS you can instead right-click the app and choose **Open**, which offers an **Open** button in the warning dialog; recent versions have removed that shortcut for unsigned apps in favor of the Privacy & Security panel.
+
+### Linux
+
+1. Download `OpenAnsho-linux.tar.gz` from the `linux` folder.
+2. Extract it and run the binary:
+
+```bash
+tar -xzf OpenAnsho-linux.tar.gz
+./OpenAnsho
+```
+
+The binary inside the archive is already marked executable, so no `chmod` is needed. Extract it with `tar` rather than dragging it out of an archive viewer, since some viewers drop file permissions — if you end up with a file that won't start, `chmod +x OpenAnsho` restores it.
+
+The Linux build is produced on the current Ubuntu CI image, so it needs a reasonably recent glibc and will not run on notably older distributions. It also unpacks itself into `/tmp` at startup, which fails on systems that mount `/tmp` with `noexec`; setting `TMPDIR` to a directory that permits execution works around that.
+
+## Install with pip
+
+If you already have Python 3.9 or newer, OpenAnsho is also on PyPI:
+
+```bash
+pip install openansho
+```
+
+Then start it from a terminal:
+
+```bash
+openansho
+```
+
+`pipx install openansho` works too, and is the better choice if you would rather not add OpenAnsho (and Qt, which comes with it) to an existing environment — pipx keeps it in its own virtualenv while still putting the `openansho` command on your PATH.
+
+The pip install pulls in PySide6, which ships Qt itself; on a minimal Linux install you may still need a few system libraries (`libegl1`, `libgl1`, `libxkbcommon0`, `libxcb-cursor0` on Debian/Ubuntu). Unlike the prebuilt executables above, a pip install stores your username in a per-user config directory (`~/Library/Application Support/OpenAnsho` on macOS, `%APPDATA%\OpenAnsho` on Windows, `~/.config/openansho` on Linux), so it survives upgrading the package.
+
+If the app fails to start and you want to see why, run `python -m openansho` instead — that form keeps a console attached on Windows and prints the traceback.
+
+## Development Setup
+
+First-time setup, run once from the repo root:
+
+```bash
+python3 -m venv .venv           # create the project virtualenv
+source .venv/bin/activate       # activate it
+pip install -e ".[dev]"        # install package + dev deps (pytest, pytest-qt)
+```
+
+Every subsequent session, activate the virtualenv before running any commands below:
+
+```bash
+source .venv/bin/activate       # activate the project virtualenv
+```
+
+To run the development version of the app (with the virtualenv active):
+
+```bash
+python -m openansho              # run the app (or the `openansho` console script)
+```
+
+## Learning Vim
+
+While the app can be used using traditional controls (mouse and keyboard), you'll get the most out of Open Ansho if you learn how to navigate using Vim keybindings. There are a variety of interactive tutorials for learning Vim, such as [VimHero](https://www.vim-hero.com/), [VIM Adventures](https://vim-adventures.com/), and [OpenVim](https://openvim.com/).

openansho-0.1.0/README.md

@@ -0,0 +1,99 @@
+# Open Ansho (暗証) - Open-source qualitative data analysis
+
+Open Ansho is a free and open-source desktop app for qualitative data analysis of text documents. This was designed as a fast and focused tool with the following goals:
+
+- Fast coding: By using Vim-inspired keybindings, you can code a document without ever moving your hands off the keyboard.
+- Easy collaboration: No signup needed. All data (text and codes) are written to a database file that you can store in a shared directory (e.g., Dropbox, Google Drive, OneDrive).
+- Clarity: Visually compare overlapping code segments through vertically-separated split highlights. Easily see simultaneous coding through striped segments.
+- Lightweight: No bloat. Just fast coding.
+
+Documents can be imported as plain text (`.txt`) or Microsoft Word (`.docx`) files; Word documents are converted to plain text on import, one line per paragraph.
+
+The app opens on a built-in tutorial that walks you through coding your first document, so there is nothing to set up before trying it. The tutorial is a scratch project held in memory — code it up however you like, then use File > New Project when you're ready to work on your own data. Nothing from the tutorial is saved, so it starts fresh every time you open the app (File > Open Tutorial brings it back mid-session).
+
+This software was created using Claude Code.
+
+## Download and Run
+
+Prebuilt executables for macOS, Windows, and Linux are published on the [`builds` branch](https://github.com/zdelrosario/open-ansho/tree/builds/runs). Each build lives in its own folder named `<run number>-<commit>`; open the highest-numbered one for the most recent build, then the folder for your operating system.
+
+The app is fully self-contained — there is nothing to install, and no Python needed. On Windows and Linux, expect a few seconds of delay every time you start it: those builds are a single file that unpacks itself to a temporary directory on each launch. The macOS app is a normal bundle and starts without that pause.
+
+These builds are not code-signed, so each operating system will warn you the first time you open one. The steps below include how to get past that. If you would rather not click through a security warning, run from source instead — see [Development Setup](#development-setup).
+
+> **Tip:** OpenAnsho remembers your username in a `.openansho_user` file it writes alongside the executable (inside the app bundle, on macOS). Put the app somewhere permanent and writable — `~/Applications` on macOS, a folder under your user account such as `C:\Users\<you>\Apps` on Windows — rather than leaving it in `Downloads`. Avoid `C:\Program Files`, which a standard account cannot write to. Replacing the app with a newer build starts you over with a fresh username file.
+
+### Windows
+
+1. Download `OpenAnsho.exe` from the `windows` folder.
+2. Double-click it.
+3. Windows SmartScreen will likely say it "protected your PC". Click **More info**, then **Run anyway**.
+
+### macOS
+
+1. Download `OpenAnsho-mac.tar.gz` from the `mac` folder.
+2. Double-click the archive to extract `OpenAnsho.app`, then drag it to your Applications folder.
+3. Double-click the app. macOS will refuse to open it, saying the developer cannot be verified.
+4. Open **System Settings → Privacy & Security**, scroll to the Security section, and click **Open Anyway** next to the message about OpenAnsho. Confirm once more when prompted.
+
+You only need to do step 4 once. On older versions of macOS you can instead right-click the app and choose **Open**, which offers an **Open** button in the warning dialog; recent versions have removed that shortcut for unsigned apps in favor of the Privacy & Security panel.
+
+### Linux
+
+1. Download `OpenAnsho-linux.tar.gz` from the `linux` folder.
+2. Extract it and run the binary:
+
+```bash
+tar -xzf OpenAnsho-linux.tar.gz
+./OpenAnsho
+```
+
+The binary inside the archive is already marked executable, so no `chmod` is needed. Extract it with `tar` rather than dragging it out of an archive viewer, since some viewers drop file permissions — if you end up with a file that won't start, `chmod +x OpenAnsho` restores it.
+
+The Linux build is produced on the current Ubuntu CI image, so it needs a reasonably recent glibc and will not run on notably older distributions. It also unpacks itself into `/tmp` at startup, which fails on systems that mount `/tmp` with `noexec`; setting `TMPDIR` to a directory that permits execution works around that.
+
+## Install with pip
+
+If you already have Python 3.9 or newer, OpenAnsho is also on PyPI:
+
+```bash
+pip install openansho
+```
+
+Then start it from a terminal:
+
+```bash
+openansho
+```
+
+`pipx install openansho` works too, and is the better choice if you would rather not add OpenAnsho (and Qt, which comes with it) to an existing environment — pipx keeps it in its own virtualenv while still putting the `openansho` command on your PATH.
+
+The pip install pulls in PySide6, which ships Qt itself; on a minimal Linux install you may still need a few system libraries (`libegl1`, `libgl1`, `libxkbcommon0`, `libxcb-cursor0` on Debian/Ubuntu). Unlike the prebuilt executables above, a pip install stores your username in a per-user config directory (`~/Library/Application Support/OpenAnsho` on macOS, `%APPDATA%\OpenAnsho` on Windows, `~/.config/openansho` on Linux), so it survives upgrading the package.
+
+If the app fails to start and you want to see why, run `python -m openansho` instead — that form keeps a console attached on Windows and prints the traceback.
+
+## Development Setup
+
+First-time setup, run once from the repo root:
+
+```bash
+python3 -m venv .venv           # create the project virtualenv
+source .venv/bin/activate       # activate it
+pip install -e ".[dev]"        # install package + dev deps (pytest, pytest-qt)
+```
+
+Every subsequent session, activate the virtualenv before running any commands below:
+
+```bash
+source .venv/bin/activate       # activate the project virtualenv
+```
+
+To run the development version of the app (with the virtualenv active):
+
+```bash
+python -m openansho              # run the app (or the `openansho` console script)
+```
+
+## Learning Vim
+
+While the app can be used using traditional controls (mouse and keyboard), you'll get the most out of Open Ansho if you learn how to navigate using Vim keybindings. There are a variety of interactive tutorials for learning Vim, such as [VimHero](https://www.vim-hero.com/), [VIM Adventures](https://vim-adventures.com/), and [OpenVim](https://openvim.com/).

openansho-0.1.0/images/kanji_shou_app_icon.svg

@@ -0,0 +1,9 @@
+<svg width="100%" viewBox="0 0 680 680" xmlns="http://www.w3.org/2000/svg" role="img" style="">
+<title style="fill:rgb(0, 0, 0);stroke:none;color:rgb(11, 11, 11);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:&quot;Anthropic Sans&quot;, -apple-system, &quot;system-ui&quot;, &quot;Segoe UI&quot;, sans-serif;font-size:16px;font-weight:400;text-anchor:start;dominant-baseline:auto">Minimalist app icon featuring the kanji 証</title>
+<desc style="fill:rgb(0, 0, 0);stroke:none;color:rgb(11, 11, 11);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:&quot;Anthropic Sans&quot;, -apple-system, &quot;system-ui&quot;, &quot;Segoe UI&quot;, sans-serif;font-size:16px;font-weight:400;text-anchor:start;dominant-baseline:auto">A rounded-square app icon with a deep navy background and the kanji character 証, meaning proof or certificate, centered in cream, with a small red seal accent in the corner.</desc>
+<rect x="40" y="40" width="600" height="600" rx="140" fill="#1c2b45" style="fill:rgb(28, 43, 69);stroke:none;color:rgb(11, 11, 11);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:&quot;Anthropic Sans&quot;, -apple-system, &quot;system-ui&quot;, &quot;Segoe UI&quot;, sans-serif;font-size:16px;font-weight:400;text-anchor:start;dominant-baseline:auto"/>
+<rect x="88" y="88" width="504" height="504" rx="100" fill="none" stroke="#f2ead9" stroke-width="2" opacity="0.35" style="fill:none;stroke:rgb(242, 234, 217);color:rgb(11, 11, 11);stroke-width:2px;stroke-linecap:butt;stroke-linejoin:miter;opacity:0.35;font-family:&quot;Anthropic Sans&quot;, -apple-system, &quot;system-ui&quot;, &quot;Segoe UI&quot;, sans-serif;font-size:16px;font-weight:400;text-anchor:start;dominant-baseline:auto"/>
+<text x="340" y="365" text-anchor="middle" dominant-baseline="central" font-family="'Hiragino Mincho ProN','Noto Serif JP',serif" font-size="360" font-weight="400" fill="#f2ead9" style="fill:rgb(242, 234, 217);stroke:none;color:rgb(11, 11, 11);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:&quot;Hiragino Mincho ProN&quot;, &quot;Noto Serif JP&quot;, serif;font-size:360px;font-weight:400;text-anchor:middle;dominant-baseline:central">証</text>
+<circle cx="520" cy="520" r="46" fill="none" stroke="#c1443a" stroke-width="10" style="fill:none;stroke:rgb(193, 68, 58);color:rgb(11, 11, 11);stroke-width:10px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:&quot;Anthropic Sans&quot;, -apple-system, &quot;system-ui&quot;, &quot;Segoe UI&quot;, sans-serif;font-size:16px;font-weight:400;text-anchor:start;dominant-baseline:auto"/>
+<circle cx="520" cy="520" r="8" fill="#c1443a" style="fill:rgb(193, 68, 58);stroke:none;color:rgb(11, 11, 11);stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;opacity:1;font-family:&quot;Anthropic Sans&quot;, -apple-system, &quot;system-ui&quot;, &quot;Segoe UI&quot;, sans-serif;font-size:16px;font-weight:400;text-anchor:start;dominant-baseline:auto"/>
+</svg>

openansho-0.1.0/pyproject.toml

@@ -0,0 +1,97 @@
+[build-system]
+# 1.27 is the first hatchling that understands PEP 639 (`license`/`license-files`).
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "openansho"
+dynamic = ["version"]
+description = "Open-source qualitative data analysis"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+authors = [{ name = "Zachary del Rosario", email = "zdelrosario@olin.edu" }]
+keywords = [
+    "qualitative-data-analysis",
+    "qda",
+    "coding",
+    "codebook",
+    "research",
+    "vim",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: MacOS X",
+    "Environment :: Win32 (MS Windows)",
+    "Environment :: X11 Applications :: Qt",
+    "Intended Audience :: Education",
+    "Intended Audience :: Science/Research",
+    "Operating System :: MacOS",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+    "Topic :: Text Processing :: Linguistic",
+]
+dependencies = [
+    "PySide6>=6.6",
+]
+
+[project.urls]
+Homepage = "https://github.com/zdelrosario/open-ansho"
+Repository = "https://github.com/zdelrosario/open-ansho"
+Issues = "https://github.com/zdelrosario/open-ansho/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-qt>=4.4",
+]
+build = [
+    "pyinstaller>=6.0",
+    "pillow",
+]
+# Building and uploading the sdist/wheel to PyPI (see `make dist` / `make publish`).
+publish = [
+    "build>=1.2",
+    "twine>=6.1",
+]
+
+# A gui-script rather than a console script: on Windows the launcher is built
+# against pythonw, so double-clicking or running `openansho` doesn't leave a
+# console window sitting behind the app. On macOS/Linux the two kinds of entry
+# point are identical. `python -m openansho` still runs it with a console
+# attached, which is the way to see a traceback on Windows.
+[project.gui-scripts]
+openansho = "openansho.__main__:main"
+
+[tool.hatch.version]
+path = "src/openansho/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/openansho"]
+
+# The app icon lives at the repo root for PyInstaller's sake (see the Makefile),
+# but an installed copy has no repo around it — so ship the icon inside the
+# package too, where `__main__._icon_path` looks for it.
+[tool.hatch.build.targets.wheel.force-include]
+"images/kanji_shou_app_icon.png" = "openansho/kanji_shou_app_icon.png"
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src",
+    "/tests",
+    "/images",
+    "/Makefile",
+    "/README.md",
+    "/CLAUDE.md",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

openansho-0.1.0/src/openansho/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"