chktm 0.1.0__tar.gz

chktm-0.1.0/.claude/settings.local.json

@@ -0,0 +1,45 @@
+{
+  "permissions": {
+    "allow": [
+      "WebSearch",
+      "WebFetch(domain:data.uspto.gov)",
+      "WebFetch(domain:www.uspto.gov)",
+      "WebFetch(domain:developer.uspto.gov)",
+      "WebFetch(domain:bulkdata.uspto.gov)",
+      "Bash(sudo dnf:*)",
+      "WebFetch(domain:catalog.data.gov)",
+      "Bash(pdftotext \"/home/nickschuetz/.config/claude-code/personal/projects/-home-nickschuetz-code-chktm/f5ff2b24-6468-4643-b31e-1e92f19055ff/tool-results/webfetch-1775849848164-30lf7k.pdf\" -)",
+      "Bash(curl -s 'https://data.uspto.gov/api/v1/datasets/products/search?productTitle=Trademark')",
+      "Bash(curl -s -H 'Accept: application/json' 'https://data.uspto.gov/ptab-api/search/products?rows=50&start=0&largeTextSearchFlag=N&productTitle=Trademark')",
+      "Bash(python3 -m json.tool)",
+      "Bash(curl -sv 'https://data.uspto.gov/api/v1/search/products?rows=50&start=0&largeTextSearchFlag=N&productTitle=Trademark')",
+      "WebFetch(domain:github.com)",
+      "Bash(curl -s -H 'Accept: application/json' -H 'X-API-KEY: dummy' 'https://data.uspto.gov/api/v1/bulk-data/product/TRTDXFAP')",
+      "Bash(curl -s -H 'Accept: application/json' 'https://api.uspto.gov/v1/bulk-data/product/TRTDXFAP')",
+      "Bash(curl -s -H 'Accept: application/json' 'https://api.uspto.gov/v3/bulk-data/products/TRTDXFAP/files?rows=5&start=0')",
+      "Bash(pdftotext \"/home/nickschuetz/.config/claude-code/personal/projects/-home-nickschuetz-code-chktm/f5ff2b24-6468-4643-b31e-1e92f19055ff/tool-results/webfetch-1775850107225-n96rdd.pdf\" -)",
+      "Bash(curl -sI 'https://bulkdata.uspto.gov/data/trademark/dailyxml/applications/apc260101.zip')",
+      "Bash(curl -s 'https://api.uspto.gov/v3/bulk-data/products?productNameFilter=Trademark' -H 'Accept: application/json')",
+      "Bash(curl -sv 'https://bulkdata.uspto.gov/data/trademark/dailyxml/applications/')",
+      "Bash(curl -s 'https://api.uspto.gov/api/v1/datasets/products/search?q=Trademark&limit=20&offset=0' -H 'Accept: application/json')",
+      "Bash(curl -s -o /tmp/bdss-odp-mapping.pdf 'https://data.uspto.gov/documents/documents/BDSS-to-ODP-API-Mapping.pdf')",
+      "Bash(pdftotext /tmp/bdss-odp-mapping.pdf -)",
+      "WebFetch(domain:raw.githubusercontent.com)",
+      "Bash(curl -s 'https://raw.githubusercontent.com/patent-dev/uspto-odp/main/swagger_fixed.yaml')",
+      "Bash(curl -s 'https://raw.githubusercontent.com/patent-dev/uspto-odp/main/client.go')",
+      "WebFetch(domain:uspto.report)",
+      "Bash(python3 -m pip install -e /home/nickschuetz/code/chktm)",
+      "Bash(dnf list:*)",
+      "Bash(PYTHONPATH=src python3:*)",
+      "Bash(python3 -m ensurepip)",
+      "Bash(python3 -m pip install pytest typer rich --quiet)",
+      "Bash(python3 -m pip install defusedxml --quiet)",
+      "Bash(python3:*)",
+      "Bash(echo \"exit: $?\")",
+      "Bash(mkdir -p /mnt/d/Storage/claude/chktm)",
+      "Bash(mv /home/nickschuetz/code/chktm/data/* /mnt/d/Storage/claude/chktm/)",
+      "Bash(rmdir /home/nickschuetz/code/chktm/data)",
+      "Bash(PYTHONPATH=src CHKTM_DATA_DIR=/mnt/d/Storage/claude/chktm python3:*)"
+    ]
+  }
+}

chktm-0.1.0/.gitignore

@@ -0,0 +1,210 @@
+# chktm data directory (downloaded USPTO bulk data + SQLite DB)
+data/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/

chktm-0.1.0/AGENTS.md

@@ -0,0 +1,76 @@
+# AGENTS.md
+
+Instructions for AI coding agents working in this repo.
+
+## Source of truth
+
+`SPEC.md` is the authoritative scope for v0.1. If this file and SPEC.md disagree
+about *what* to build, SPEC.md wins. This file governs *how* to build it.
+
+Anything not in SPEC.md's v0.1 scope goes in `BACKLOG.md`, not in the code.
+
+## Build in phases, stop between them
+
+SPEC.md defines five phases. Treat the stops between phases as hard stops:
+finish the phase, report results to the human, and wait for a go-ahead before
+starting the next one. Do not chain phases together unprompted.
+
+Phase 1 in particular is a **recon-only** phase. Do not write application code
+during Phase 1. Verify the live USPTO Open Data Portal (data.uspto.gov) details
+firsthand — URL patterns, file formats, schema, update cadence — and produce a
+short written recon report. The rest of the build depends on this being right.
+
+## Time budget
+
+Target: 8–12 hours total across all phases.
+Hard stop: 16 hours. If you hit 16 hours and v0.1 is not shipped, stop and
+surface the problem. Do not silently keep going.
+
+## Scope discipline
+
+- If a change feels like it's growing the scope, stop and ask.
+- "While I'm here" refactors are not free. Skip them unless they're load-bearing
+  for the current phase.
+- New dependencies need a one-line justification in the commit message.
+- DuckDB vs SQLite is an open call per SPEC.md — if you pick DuckDB, document
+  why in the commit and in `README.md`.
+
+## Commits
+
+- Sign off every commit: `git commit -s` (DCO, no CLA — see SPEC.md).
+- Conventional-ish messages are fine but not required. Clarity beats format.
+- One logical change per commit. Recon notes, schema, ingest, fetch, search,
+  report, docs — these should not all land in one commit.
+- Never commit downloaded USPTO data, the SQLite database, or anything under
+  `data/`. Add to `.gitignore` early.
+
+## Code conventions
+
+- Python 3.11+.
+- `pyproject.toml` with `hatchling` or `setuptools` — your call, document it.
+- Formatter: `ruff format`. Linter: `ruff check`. No black, no flake8, no isort.
+- Type hints on all public functions. `from __future__ import annotations` at
+  the top of every module.
+- Apache-2.0 SPDX header at the top of every source file:
+  `# SPDX-License-Identifier: Apache-2.0`
+- CLI framework: Typer (per SPEC.md). Don't substitute Click or argparse.
+
+## Testing
+
+- `pytest`. Fixtures live under `tests/fixtures/`.
+- Every module in `src/chktm/` should have a corresponding `test_*.py`.
+- Tests must not hit the network. If a test needs USPTO data, it uses a
+  checked-in fixture XML file under `tests/fixtures/`.
+- `pytest` with no arguments must pass before any phase is considered done.
+
+## The disclaimer is load-bearing
+
+chktm is a research aid, not legal clearance. That sentence (or a close
+variant) must appear in: `README.md`, `--help` output, every generated report,
+and the top of `src/chktm/disclaimer.py` as the single source of truth that
+the other surfaces import from. Do not paraphrase it into something softer.
+
+## When in doubt
+
+Stop and ask the human. A two-line clarifying question is cheaper than an
+hour of work in the wrong direction.

chktm-0.1.0/BACKLOG.md

@@ -0,0 +1,61 @@
+# Backlog
+
+Items explicitly deferred from v0.1. These are not bugs — they are conscious
+scope boundaries. PRs for these items should open an issue for discussion first.
+
+## Search improvements
+
+- **Fuzzy matching** — Levenshtein distance, n-gram similarity for catching
+  near-miss typos (e.g., "thundercorp" vs "thundrcorp")
+- **Phonetic matching** — Soundex, Metaphone, or Double Metaphone for catching
+  sound-alike marks (e.g., "Hella" vs "Hela")
+- **Weighting/scoring** — More nuanced risk scoring beyond the current three-tier
+  system (exact match weight, prefix match, class distance)
+
+## Data sources
+
+- **Multi-jurisdiction** — EU (EUIPO), UK (IPO), WIPO Madrid Protocol, Canada
+  (CIPO). Each has its own bulk data format.
+- **Common-law usage checks** — Search Steam, itch.io, GitHub, app stores for
+  unregistered marks in the same space
+- **TSDR real-time lookup** — Query `tsdrapi.uspto.gov` for individual case
+  details (different API, different key)
+- **Official status codes table** — Download and parse
+  `Table1TrademarkStatusCodes_20250813.doc` for the definitive live/dead mapping
+  instead of the current range-based heuristic
+
+## Distribution
+
+- **PyPI publishing** — `pip install chktm` instead of `pipx install git+...`
+- **Homebrew formula** — For macOS users
+- **Pre-built container images** — Automated CI/CD to build and push to quay.io
+  on tag
+
+## Web UI
+
+- **Saved searches** — Persist search queries for monitoring over time
+- **Diff reports** — Compare results between runs to surface new conflicts
+- **Authentication** — OAuth proxy or basic auth for the web UI and MCP endpoints
+- **Rate limiting** — Per-client rate limiting on the web API
+
+## Infrastructure
+
+- **CI/CD pipeline** — GitHub Actions for tests, linting, container builds
+- **Helm chart** — Parameterized OpenShift/Kubernetes deployment
+- **CycloneDX SBOM export** — Machine-readable SBOM in addition to the current
+  human-readable `SBOM.md`
+- **Database backend alternatives** — PostgreSQL or DuckDB for multi-replica
+  deployments where SQLite's single-writer limitation is a problem
+
+## Agent integration
+
+- **MCP authentication** — Token-based auth for the MCP endpoints
+- **Batch monitoring** — MCP tool to search a large watchlist of terms on a
+  schedule and report only new/changed results since last check
+- **Monitoring tool** — MCP tool to set up alerts when new marks are filed that
+  match a watched term
+
+## Documentation
+
+No outstanding documentation items. Man page at `docs/chktm.1`, API reference
+at `/docs` (Swagger UI) and `/redoc` (ReDoc) are included in v0.1.

chktm-0.1.0/CHANGELOG.md

@@ -0,0 +1,143 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Project skeleton: `pyproject.toml` (hatchling), `src/chktm/` package layout
+- `schema.py` — SQLite schema (marks, mark_classes, meta tables), text
+  normalization, date parsing, status-code live/dead heuristic
+- `ingest.py` — Streaming XML parser using `defusedxml.ElementTree.iterparse`
+  with batched upserts and memory-bounded processing
+- `cli.py` — Typer CLI with commands: `init`, `update`, `search`, `status`,
+  `version`. All commands support `--json` for structured machine-readable output
+- `disclaimer.py` — Single source of truth for legal disclaimer text
+- `bulk_ingest_mode()` context manager for tuned SQLite writes
+  (`synchronous=NORMAL`, 64 MB cache)
+- `CHKTM_DATA_DIR` environment variable support for overriding default data
+  directory
+- Stable exit codes: 0 (success), 1 (error), 2 (no database)
+- `fetch.py` — Download module for USPTO ODP API with rate limiting
+  (4 ZIP/min), progress callbacks, resumability via file-size checks and
+  meta table tracking
+- `search.py` — Query engine with normalized substring matching, class
+  filtering, and risk-tier classification (HIGH/MEDIUM/LOW)
+- `report.py` — Markdown and JSON report rendering grouped by risk tier,
+  with disclaimer and TSDR links
+- `chktm init` — Full pipeline: download annual backfile + daily files,
+  extract, ingest into SQLite, with Rich progress bars
+- `chktm update` — Incremental daily file download and ingest since last
+  update date
+- `chktm search` — Fully implemented with `--classes`, `--include-dead`,
+  `--out`, and `--json` flags
+- Test suite: 54 tests covering schema utilities, ingest, search, and
+  report rendering
+- Test fixtures: `sample_edge_cases.xml` (synthetic), `sample_daily.xml`
+  (extracted from USPTO daily file)
+- `web.py` — FastAPI web application with lightweight search UI and REST API
+  (`GET /`, `GET /api/status`, `GET /api/search`)
+- `mcp_server.py` — MCP (Model Context Protocol) server with `search_trademarks`
+  and `corpus_status` tools. Supports stdio, SSE, and Streamable HTTP transports
+- `chktm serve` — CLI command to start the combined web UI + MCP server
+- `Containerfile` — Multi-stage build for quay.io, runs as non-root (UID 1001),
+  PVC mount at `/data` for the SQLite database
+- OpenShift deployment manifests in `deploy/openshift/`:
+  Namespace, PVC, Secret, init Job, Deployment, Service, Route, update CronJob
+- `docs/deployment.md` — Full deployment guide for OpenShift with quay.io,
+  including MCP client configuration
+- `SBOM.md` — Software Bill of Materials listing all direct and transitive
+  dependencies with licenses
+- `docs/architecture.md` — Data flow, module responsibilities, database schema,
+  security model, AI agent interface contract
+- `docs/recon-phase1.md` — Phase 1 recon report documenting USPTO ODP API
+  findings, XML schema, status codes, rate limits, and gotchas
+- `README.md` — Project overview, quickstart, CLI reference, known limitations
+- `CONTRIBUTING.md` — DCO sign-off, scope philosophy, setup, code style
+- `BACKLOG.md` — Deferred items: fuzzy matching, multi-jurisdiction, PyPI, etc.
+- `CODE_OF_CONDUCT.md` — Contributor Covenant v2.1
+- `SECURITY.md` — Threat model, OWASP Top 10 compliance mapping, vuln reporting
+- `docs/usage-guide.md` — Search best practices, class selection, risk tier
+  interpretation, agent efficiency tips for minimizing tokens/round-trips
+- `docs/chktm.1` — Man page covering all commands, options, exit codes,
+  environment variables, config files, endpoints, and examples
+- Interactive API reference at `/docs` (Swagger UI) and `/redoc` (ReDoc)
+  auto-generated by FastAPI from endpoint definitions
+- `docs/testing-mcp.md` — Step-by-step MCP Inspector testing guide covering
+  Streamable HTTP, SSE, stdio, and CLI modes on all platforms
+- Multiplatform documentation: all install, env var, and MCP config examples
+  include Linux, macOS, and Windows variants
+- Version centralized in `src/chktm/__init__.py` — single source of truth for
+  CLI, web app, API responses, MCP protocol handshake, and pyproject.toml
+- `--report legal` flag on `chktm search` — generates attorney-ready report
+  with executive summary, component word analysis (auto-splits compound terms),
+  risk assessment grouped by owner, limitations, and recommended next steps
+- `generate_legal_report` MCP tool — same legal report available to AI agents
+- PDF output for legal reports — `--out report.pdf` auto-detected from file
+  extension. Professional formatting with tables, color-coded risk tiers,
+  section headings, and print-ready layout. Uses `fpdf2` (pure Python, LGPL-3.0)
+- `config.py` — Persistent config file (`~/.config/chktm/config.toml` on
+  Linux/macOS, `%APPDATA%\chktm\config.toml` on Windows). Saves data directory
+  during init so subsequent commands find the database automatically.
+  Resolution order: `--data-dir` flag > `CHKTM_DATA_DIR` env > config > `./data`
+
+### Security
+- XML parsing hardened with `defusedxml` to block entity expansion, XXE, and
+  DTD retrieval attacks
+- All SQL queries use parameterized statements (`?` placeholders)
+- SQL LIKE wildcards (`%`, `_`) escaped in user search terms to prevent
+  unintended pattern matching (OWASP A03:2021)
+- Security headers on all web responses: CSP, X-Content-Type-Options, 
+  X-Frame-Options, Referrer-Policy, Permissions-Policy (OWASP A05:2021)
+- Input validation: query length (500 chars), term count (20), class count (45),
+  per-term length (200 chars), result cap (1,000 per term) (OWASP A04:2021)
+- API key read from environment variable, never logged or committed
+- Filename sanitization on downloads to prevent path traversal (OWASP A04)
+- International class range validation (1-45) on web API (OWASP A04)
+- Generic error messages to clients — internal paths no longer exposed (OWASP A01)
+- `Strict-Transport-Security` (HSTS) header added (OWASP A05)
+- `Cache-Control: no-store` header to prevent caching of search results
+- Container hardened for OpenShift `restricted` SCC: arbitrary UID with GID 0,
+  `readOnlyRootFilesystem`, `drop: ALL` capabilities, `runAsNonRoot`,
+  `seccompProfile: RuntimeDefault`, `automountServiceAccountToken: false`
+- All OpenShift manifests include pod and container security contexts
+
+### Resilience
+- Per-file retry with exponential backoff (2s, 4s, 8s) on network errors,
+  HTTP 429 (with Retry-After), and HTTP 5xx server errors
+- Download integrity check: verifies file size matches API metadata after
+  download, deletes and retries on mismatch
+- Disk space check before `init` starts (~30 GB required)
+- Corrupt ZIP handling: `zipfile.BadZipFile` caught and logged, file deleted
+  and skipped instead of crashing the pipeline
+- Graceful SIGINT/SIGTERM shutdown: finishes current file, commits to DB,
+  exits cleanly. Re-run to resume.
+- Non-ZIP files in product listings (`.doc`, `.pdf`) filtered out
+- JSON progress events emitted in `--json` mode for container/CI monitoring
+- ETA display in progress bar based on running average per file
+
+### Performance
+- `pipeline.py` — Pipelined download + ingest using producer/consumer threading;
+  overlaps file download with ingest of the previous file (~20-25% faster)
+- `--off-peak` flag on `init` and `update` — uses USPTO off-peak rate limits
+  (12 req/min vs 4 req/min, ~3x faster downloads between 10pm-5am EST)
+- `--stream-ingest` flag — streams XML directly from ZIP to parser without
+  writing to disk (lower I/O, same memory via streaming decompression)
+- ZIP files deleted after successful ingestion by default to save disk space;
+  `--keep-zips` flag on `init` and `update` to retain them
+- WAL checkpoint (`PRAGMA wal_checkpoint(TRUNCATE)`) after init/update completes
+  to consolidate the WAL file into the main database
+- Stack-based parent tracking in iterparse prevents memory leak on large files
+- Batched DELETE for class associations using `WHERE IN` (999-element chunks)
+  instead of per-row deletes
+- N+1 class query elimination — batch-fetches class associations in a single
+  chunked `WHERE IN` query instead of one query per match
+- Composite index `(is_live, wordmark_normalized)` for faster filtered searches
+- MCP server instructions trimmed from ~460 to ~80 tokens per connection
+- Legal report component searches exclude dead marks and truncate goods/services
+  to reduce MCP response token usage
+- SQLite bulk-ingest pragmas (`synchronous=NORMAL`, `cache_size=-64000`)
+  applied during ingestion via context manager

chktm-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,12 @@
+# Code of Conduct
+
+This project follows the [Contributor Covenant v2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+
+By participating in this project, you agree to abide by its terms.
+
+## Reporting
+
+If you experience or witness unacceptable behavior, please report it by opening
+a GitHub issue or contacting the maintainer directly.
+
+Reports will be reviewed and responded to promptly.

chktm-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,129 @@
+# Contributing to chktm
+
+Thanks for your interest in contributing. chktm is deliberately small — it does
+one thing (trademark screening) and tries to do it well.
+
+## Scope philosophy
+
+We are deliberately small. Features outside the v0.1 scope are tracked in
+[BACKLOG.md](BACKLOG.md) and considered case-by-case. PRs that add scope without
+discussion will be asked to open an issue first.
+
+## Getting started
+
+### Prerequisites
+
+- Python 3.11+ (Linux, macOS, or Windows)
+- Git
+- A free [USPTO ODP API key](https://data.uspto.gov/apis/getting-started)
+  (only needed for `chktm init` / `chktm update`, not for development)
+
+### Setup
+
+**Linux / macOS:**
+
+```bash
+git clone https://github.com/nickschuetz/chktm.git
+cd chktm
+pip install -e .
+```
+
+**Windows (PowerShell):**
+
+```powershell
+git clone https://github.com/nickschuetz/chktm.git
+cd chktm
+pip install -e .
+```
+
+The install command is identical across platforms. If your system uses `pip3`
+instead of `pip`, substitute accordingly.
+
+### Run tests
+
+**All platforms:**
+
+```bash
+pytest
+```
+
+Tests must not hit the network. They use checked-in fixture XML files under
+`tests/fixtures/`. All tests must pass before any PR is merged.
+
+### Code style
+
+- Formatter: `ruff format`
+- Linter: `ruff check`
+- Type hints on all public functions
+- `from __future__ import annotations` at the top of every module
+- Apache-2.0 SPDX header at the top of every source file:
+  `# SPDX-License-Identifier: Apache-2.0`
+
+**All platforms:**
+
+```bash
+ruff format src/ tests/
+ruff check src/ tests/
+```
+
+### Platform notes for contributors
+
+- **Paths:** Always use `pathlib.Path`, never hardcoded `/` or `\` separators.
+- **Environment variables:** Document both `export` (Linux/macOS) and
+  `$env:` (Windows PowerShell) forms when referencing env vars in docs.
+- **Line endings:** The repo uses LF line endings. Git's `core.autocrlf`
+  handles conversion on Windows.
+- **Shell commands:** If a command differs between platforms, show all variants.
+  Commands that work identically everywhere need only be shown once.
+
+## Commits
+
+### DCO sign-off
+
+All commits must be signed off under the
+[Developer Certificate of Origin](https://developercertificate.org/):
+
+```bash
+git commit -s -m "your commit message"
+```
+
+This adds a `Signed-off-by:` line to your commit message, certifying that you
+wrote the code or have the right to submit it under the project's license.
+
+### Commit messages
+
+- Clarity beats format. Conventional commits are fine but not required.
+- One logical change per commit.
+- Never commit downloaded USPTO data, the SQLite database, or anything under
+  `data/`.
+
+## Pull requests
+
+1. Open an issue first for anything beyond a trivial bug fix.
+2. Keep PRs focused — one logical change per PR.
+3. All tests must pass.
+4. `ruff format` and `ruff check` must pass with no errors.
+5. Update `CHANGELOG.md` under `[Unreleased]` with a brief description.
+
+## What not to contribute (yet)
+
+These are tracked in BACKLOG.md and not ready for PRs:
+
+- Fuzzy/phonetic matching
+- Web UI beyond the current lightweight search form
+- Multi-jurisdiction support
+- PyPI publishing
+- Common-law usage checks
+
+If you want to work on any of these, open an issue to discuss approach first.
+
+## The disclaimer is load-bearing
+
+chktm is a research aid, not legal clearance. That sentence must appear in:
+the README, `--help` output, every generated report, and `src/chktm/disclaimer.py`
+as the single source of truth. Do not paraphrase it into something softer.
+
+## Questions?
+
+Open an issue. A two-line clarifying question is cheaper than an hour of work
+in the wrong direction.