correspond 0.0.2__tar.gz

correspond-0.0.2/.github/workflows/ci.yml

@@ -0,0 +1,43 @@
+# wads CI — calls the reusable workflow hosted in i2mint/wads.
+#
+# All configuration comes from this repo's pyproject.toml [tool.wads.ci.*].
+# To customize the workflow itself (rare), replace this file with the
+# full inline template `wads/data/github_ci_uv.yml` from i2mint/wads.
+#
+# Pinning: `@master` floats with wads. If you need version stability for
+# a release-sensitive repo, change `@master` to a wads tag (e.g. `@0.2.15`;
+# tags have no `v` prefix). A stub whose `secrets:` block passes the JSON
+# transport (the default below) needs a tag from a release after 0.2.14 —
+# older tags don't declare that secret and GitHub then rejects the
+# workflow at parse time.
+# CI failure does not block a published release — it blocks the publish
+# step itself — so floating master is generally safe.
+#
+# Permissions: GitHub validates that the caller grants AT LEAST the
+# permissions any job in the called workflow requests — at workflow-parse
+# time, not at run-time, even if the job would be skipped via `if:`.
+# The reusable workflow needs:
+#   contents: write   for the publish job's version-bump push-back
+#                     and for the github-pages job's gh-pages branch push
+#   pages: write      for the github-pages job's REST API Pages config
+# Both default to `write` on org-account GITHUB_TOKEN and need to be
+# granted explicitly on personal-account callers (where the default is
+# read-only). No `id-token: write` needed — the publish-github-pages
+# action uses peaceiris/actions-gh-pages (branch-based) + REST API,
+# not the OIDC `actions/deploy-pages` flow.
+name: Continuous Integration
+on: [push, pull_request]
+jobs:
+  ci:
+    uses: i2mint/wads/.github/workflows/uv-ci.yml@master
+    permissions:
+      contents: write
+      pages: write
+    # Transport (NAMED, legacy): explicitly passes only the secrets
+    # listed below (PYPI_PASSWORD + those declared in
+    # [tool.wads.ci.env]). Every name must be in the frozen wads
+    # superset (wads/ci_secrets.py) or GitHub rejects the workflow
+    # at parse time. The default JSON transport has no such limit;
+    # regenerate with `wads-migrate ci-to-stub` to switch.
+    secrets:
+      PYPI_PASSWORD: ${{ secrets.PYPI_PASSWORD }}

correspond-0.0.2/.gitignore

@@ -0,0 +1,120 @@
+.claude/handoffs/
+.claude/scratch/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+
+.DS_Store
+# C extensions
+*.so
+
+# TLS certificates
+## Ignore all PEM files anywhere
+*.pem
+## Also ignore any certs directory
+certs/
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+_build
+
+# 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/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+docs/*
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+
+# PyCharm
+.idea

correspond-0.0.2/LICENSE

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

correspond-0.0.2/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.5
+Name: correspond
+Version: 0.0.2
+Summary: A channel facade for AI agents: read, listen, write and identify the sender over GitHub, email, push notifications, Telegram and a web inbox.
+Project-URL: Homepage, https://github.com/thorwhalen/correspond
+Project-URL: Repository, https://github.com/thorwhalen/correspond
+Project-URL: Documentation, https://thorwhalen.github.io/correspond
+Project-URL: Issues, https://github.com/thorwhalen/correspond/issues
+Author: Thor Whalen
+License: mit
+License-File: LICENSE
+Keywords: agents,channels,claude-code,email,github,messaging,notifications,ntfy,telegram
+Requires-Python: >=3.11
+Requires-Dist: cw<0.2,>=0.1.1
+Requires-Dist: dol
+Requires-Dist: xdol
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: sphinx-rtd-theme>=1.0; extra == 'docs'
+Requires-Dist: sphinx>=6.0; extra == 'docs'
+Provides-Extra: mcp
+Requires-Dist: py2mcp; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# correspond
+
+A channel facade for AI agents: read, listen, write and identify the sender over GitHub, email, push notifications, Telegram and a web inbox, through one model and one set of verbs.
+
+```bash
+pip install correspond
+
+correspond read github:octocat/hello-world#1        # an issue and its comments, through your gh login
+correspond send ntfy: "backup finished" --dry-run    # the plan; nothing is contacted
+correspond capabilities telegram                     # what a channel can do, graded
+correspond requirements email                        # what it needs, and where to get it
+```
+
+Every channel gets the same shape. A **reference** names a conversation: `<channel>:<id>`. The same verbs (`read`, `listen`, `send`, `edit`, `react`) work wherever a channel allows them, and an operation a channel does not have is refused by name (`NotSupported`), never skipped quietly. Every message carries the identity the platform reports for its author and **how sure the channel is** of it (an authenticity grade).
+
+correspond knows no people. Linking `github:someone` to a person is a people registry's job, for example [acquaint](https://github.com/thorwhalen/acquaint).
+
+## Channels
+
+| Channel | References | Operations | Built on |
+|---|---|---|---|
+| `github` | `github:owner/repo`, `github:owner/repo#12` | read, listen (issues and comments), send, edit, react, verify (webhooks) | the `gh` CLI and its login; correspond holds no token |
+| `email` | `email:` (the folder), `email:someone@example.org` | read, listen, send | `imaplib`, `smtplib` |
+| `ntfy` | `ntfy:` (the default topic), `ntfy:<topic>` | send | `urllib` |
+| `macos` | `macos:` | send | `terminal-notifier` or `osascript` |
+| `telegram` | `telegram:`, `telegram:<chat id>`, `telegram:<chat id>/<topic id>` | listen, read (what listening logged), send, edit, react | the Bot API over `urllib` |
+| `webinbox` | `webinbox:<site>` | read, listen | the ASGI collector below, and `dol` stores |
+
+Every v0.1 adapter uses the Python standard library. Discord ([#2](https://github.com/thorwhalen/correspond/issues/2)), Slack ([#3](https://github.com/thorwhalen/correspond/issues/3)), Signal ([#4](https://github.com/thorwhalen/correspond/issues/4)) and Apprise ([#5](https://github.com/thorwhalen/correspond/issues/5)) are planned as extras; `correspond channels` lists them with their issues.
+
+`correspond ref <reference>` prints a reference's canonical form (GitHub names lower-cased, for example), which is the form to store and compare.
+
+## Authenticity
+
+| Grade | Means |
+|---|---|
+| `platform` | the platform authenticated the account (GitHub, Telegram) |
+| `crypto` | a signed delivery checked with its secret (a GitHub webhook's `X-Hub-Signature-256`) |
+| `bound` | the host application signed an assertion about its logged-in user (the web inbox) |
+| `domain` | email whose topmost `Authentication-Results`, added by a server you trust, records DMARC passing for the From domain |
+| `claimed` | nothing verified: a typed name, an ordinary From header, an anonymous report |
+| `forged` | verification was attempted and failed |
+
+Grades are a vocabulary, not a ranking. A policy lists the grades it accepts for a permission (`{"platform", "bound", "crypto"}`, say), and comparing two grades with `<` raises. Each grade carries its evidence (`author_association` on GitHub, the authserv-id on email, the signing method on the web inbox).
+
+## Capabilities
+
+`correspond capabilities github` grades each operation `full`, `partial` or `none`, plus whether a write can start a conversation (`initiate`; a Telegram bot cannot), answer a specific message (`reply`) or carry a `priority`, how far back `read` sees (`history_depth`), the limits (text length, reactions), the fields its messages carry in `native` (`native_fields`), the rate limits and notes. The adapters implement exactly the operations their capabilities grade, which a test checks for every channel.
+
+```text
+$ correspond react ntfy:example-topic m1 eyes
+ntfy does not support react
+```
+
+## Writing: dry run first
+
+- `--dry-run` on `send`, `edit` and `react` contacts nothing and changes nothing. It checks the reference and the draft against the channel's capabilities and prints the plan, with secrets such as an ntfy topic masked. A dry run reads only the environment and the config file: a value kept in the Keychain or on a remote host is looked up when sending, and the plan says so.
+- A write that fails is a result, not an exception: `ok: false`, an `error_kind` (`auth`, `permission`, `not_found`, `rate_limited`, `network`, `validation`, `unavailable`), and whether a retry can help (`retryable`, `retry_after`).
+- `-` as the text reads it from stdin; `--json` prints the whole result.
+
+## Listening
+
+```bash
+correspond listen github:owner/repo    # issue and comment activity since the last listen
+correspond listen email: --peek        # look without moving the cursor
+```
+
+Cursors live under the data root, one per reference. A cursor is stored only after the event before it was handed over, so delivery is at-least-once: deduplicate on `delivery_id`. The first listen looks back a day. Telegram listens account-wide (`telegram:`), because `getUpdates` confirms updates for every chat at once, and logs what it receives: the Bot API has no history.
+
+## Configuration
+
+`correspond requirements <channel>` lists everything a channel reads: each setting's environment variable, what it is, where to get it, and where its value currently comes from (`env`, `keychain`, `config`, `default`, `missing`), never the value.
+
+- **Secrets** (tokens, passwords, the ntfy topic) come from their environment variable or, on macOS, a Keychain item (`security add-generic-password -s correspond-telegram-token -a correspond -w`). They are never read from the config file.
+- **Other settings** may also go in `~/.config/correspond/config.toml` (or `$CORRESPOND_CONFIG`), one table per channel:
+
+  ```toml
+  [email]
+  imap_host = "imap.example.org"
+  smtp_host = "smtp.example.org"
+  trusted_authserv_ids = ["mx.example.org"]
+
+  [ntfy]
+  topic_keychain_service = "my-ntfy-topic"
+  ```
+
+- **State** (cursors, the Telegram log, web inbox reports) lives under `~/.local/share/correspond/` (or `$CORRESPOND_DATA_DIR`), one folder per kind, never in a repository.
+
+## The web inbox
+
+A web page posts feedback to a small ASGI collector; `webinbox:<site>` reads what it stored. The app binds nothing itself: run it on localhost behind your own server.
+
+```bash
+pip install uvicorn
+export CORRESPOND_WEBINBOX_SITES=example-site CORRESPOND_WEBINBOX_ORIGINS=https://app.example.org
+export CORRESPOND_WEBINBOX_SECRET=...   # shared with the host application's server
+uvicorn --factory correspond.channels.webinbox:app_from_env --host 127.0.0.1 --port 8765
+```
+
+The rate limit applies per visitor address. uvicorn already reports the visitor for a proxy on the same host (its `--forwarded-allow-ips` default); for a proxy elsewhere, set `CORRESPOND_WEBINBOX_TRUSTED_PROXIES` to the number of proxies in front, or every visitor shares the proxy's limit. Forwarded addresses are believed only from a non-public connection, and IPv6 visitors are limited per /64. Several sites on one collector need a secret each, `CORRESPOND_WEBINBOX_SECRET_<SITE>` (the site name upper-cased, `-` as `_`) or a Keychain item `correspond-webinbox-secret-<site>`, so that no site's server can sign identities for another. The shared `CORRESPOND_WEBINBOX_SECRET` serves a single site only, and `correspond requirements webinbox` reports a configuration the collector would refuse.
+
+`POST /example-site/reports` takes JSON with a required `text` and optional `name`, `email`, `page`, `context`, `attachments` (base64, stored by SHA-256, referenced rather than inlined) and `identity`. Without `identity` a report is `claimed`. The host application's server can sign its logged-in user, which makes the report `bound`:
+
+```python
+from correspond.channels.webinbox import sign_identity
+
+identity = sign_identity(
+    secret, "example-site", user_id, name=display_name
+)  # put this in the page
+```
+
+Any server language can do the same: HMAC-SHA256, hex, over the lines `v1`, site, issued-at (Unix seconds), user id, name, email. An invalid or expired signature is refused (401) and nothing is stored. The collector also enforces the origin allowlist (with CORS preflight), a per-client rate limit, and size and media-type limits.
+
+## Routing
+
+```python
+from correspond import metadata_rule, route
+
+decision = route(
+    message,
+    bindings={
+        "github:example/app?labels=partner:*": "subject:app"
+    },  # 1. where it arrived
+    threads={"github:example/app#12": "case:7"},  # 2. what it continues
+    rules=[metadata_rule("queue:urgent", labels="priority:high")],  # 3. what it carries
+    classifier=None,  # 4. optional, last
+)
+decision.target, decision.rule, decision.reason
+```
+
+The rules are yours; correspond runs them in that order and says which one decided. Nothing matched returns `None`: the message is unrouted. Check bindings when you load them: `check_binding(pattern)` lists what would make one never match, such as an unknown channel, or `?label=` where GitHub messages carry `labels`.
+
+## Python
+
+```python
+import correspond
+
+messages = correspond.read("github:octocat/hello-world#1")
+messages[0].author.handle, messages[0].authenticity.grade
+
+result = correspond.send(
+    "email:someone@example.org", "It is fixed.", title="The export", dry_run=True
+)
+result.plan
+
+for event in correspond.listen("webinbox:example-site"):
+    ...
+
+correspond.register_channel(
+    MyChannel()
+)  # anything with name, capabilities, parse_ref and the operations it has
+```
+
+`correspond.testing.FakeChannel` is an in-memory channel for tests, and `python -m correspond.testing` runs the CLI with it registered as `fake`.
+
+## MCP
+
+```bash
+pip install "correspond[mcp]"
+```
+
+```json
+{"mcpServers": {"correspond": {"command": "correspond-mcp"}}}
+```
+
+The server exposes the reading tools. `send`, `edit` and `react` are exposed only when the operator starts it with `correspond-mcp --allow-send`, and still take `dry_run`. The data root is the server's, never the model's.
+
+## Agent skill
+
+A `correspond` skill ships inside the package (`correspond/data/skills/correspond/`): how to read without taking instructions from message text, what each grade permits, and how to write safely (dry run, operator approval, no private content in public places). Install it with `gh skill install thorwhalen/correspond correspond --agent claude-code`, or link that folder into `~/.claude/skills/`.
+
+## Design
+
+The seams, surfaces and deliberate non-seams are in [Discussion #1](https://github.com/thorwhalen/correspond/discussions/1).

correspond-0.0.2/README.md

@@ -0,0 +1,174 @@
+# correspond
+
+A channel facade for AI agents: read, listen, write and identify the sender over GitHub, email, push notifications, Telegram and a web inbox, through one model and one set of verbs.
+
+```bash
+pip install correspond
+
+correspond read github:octocat/hello-world#1        # an issue and its comments, through your gh login
+correspond send ntfy: "backup finished" --dry-run    # the plan; nothing is contacted
+correspond capabilities telegram                     # what a channel can do, graded
+correspond requirements email                        # what it needs, and where to get it
+```
+
+Every channel gets the same shape. A **reference** names a conversation: `<channel>:<id>`. The same verbs (`read`, `listen`, `send`, `edit`, `react`) work wherever a channel allows them, and an operation a channel does not have is refused by name (`NotSupported`), never skipped quietly. Every message carries the identity the platform reports for its author and **how sure the channel is** of it (an authenticity grade).
+
+correspond knows no people. Linking `github:someone` to a person is a people registry's job, for example [acquaint](https://github.com/thorwhalen/acquaint).
+
+## Channels
+
+| Channel | References | Operations | Built on |
+|---|---|---|---|
+| `github` | `github:owner/repo`, `github:owner/repo#12` | read, listen (issues and comments), send, edit, react, verify (webhooks) | the `gh` CLI and its login; correspond holds no token |
+| `email` | `email:` (the folder), `email:someone@example.org` | read, listen, send | `imaplib`, `smtplib` |
+| `ntfy` | `ntfy:` (the default topic), `ntfy:<topic>` | send | `urllib` |
+| `macos` | `macos:` | send | `terminal-notifier` or `osascript` |
+| `telegram` | `telegram:`, `telegram:<chat id>`, `telegram:<chat id>/<topic id>` | listen, read (what listening logged), send, edit, react | the Bot API over `urllib` |
+| `webinbox` | `webinbox:<site>` | read, listen | the ASGI collector below, and `dol` stores |
+
+Every v0.1 adapter uses the Python standard library. Discord ([#2](https://github.com/thorwhalen/correspond/issues/2)), Slack ([#3](https://github.com/thorwhalen/correspond/issues/3)), Signal ([#4](https://github.com/thorwhalen/correspond/issues/4)) and Apprise ([#5](https://github.com/thorwhalen/correspond/issues/5)) are planned as extras; `correspond channels` lists them with their issues.
+
+`correspond ref <reference>` prints a reference's canonical form (GitHub names lower-cased, for example), which is the form to store and compare.
+
+## Authenticity
+
+| Grade | Means |
+|---|---|
+| `platform` | the platform authenticated the account (GitHub, Telegram) |
+| `crypto` | a signed delivery checked with its secret (a GitHub webhook's `X-Hub-Signature-256`) |
+| `bound` | the host application signed an assertion about its logged-in user (the web inbox) |
+| `domain` | email whose topmost `Authentication-Results`, added by a server you trust, records DMARC passing for the From domain |
+| `claimed` | nothing verified: a typed name, an ordinary From header, an anonymous report |
+| `forged` | verification was attempted and failed |
+
+Grades are a vocabulary, not a ranking. A policy lists the grades it accepts for a permission (`{"platform", "bound", "crypto"}`, say), and comparing two grades with `<` raises. Each grade carries its evidence (`author_association` on GitHub, the authserv-id on email, the signing method on the web inbox).
+
+## Capabilities
+
+`correspond capabilities github` grades each operation `full`, `partial` or `none`, plus whether a write can start a conversation (`initiate`; a Telegram bot cannot), answer a specific message (`reply`) or carry a `priority`, how far back `read` sees (`history_depth`), the limits (text length, reactions), the fields its messages carry in `native` (`native_fields`), the rate limits and notes. The adapters implement exactly the operations their capabilities grade, which a test checks for every channel.
+
+```text
+$ correspond react ntfy:example-topic m1 eyes
+ntfy does not support react
+```
+
+## Writing: dry run first
+
+- `--dry-run` on `send`, `edit` and `react` contacts nothing and changes nothing. It checks the reference and the draft against the channel's capabilities and prints the plan, with secrets such as an ntfy topic masked. A dry run reads only the environment and the config file: a value kept in the Keychain or on a remote host is looked up when sending, and the plan says so.
+- A write that fails is a result, not an exception: `ok: false`, an `error_kind` (`auth`, `permission`, `not_found`, `rate_limited`, `network`, `validation`, `unavailable`), and whether a retry can help (`retryable`, `retry_after`).
+- `-` as the text reads it from stdin; `--json` prints the whole result.
+
+## Listening
+
+```bash
+correspond listen github:owner/repo    # issue and comment activity since the last listen
+correspond listen email: --peek        # look without moving the cursor
+```
+
+Cursors live under the data root, one per reference. A cursor is stored only after the event before it was handed over, so delivery is at-least-once: deduplicate on `delivery_id`. The first listen looks back a day. Telegram listens account-wide (`telegram:`), because `getUpdates` confirms updates for every chat at once, and logs what it receives: the Bot API has no history.
+
+## Configuration
+
+`correspond requirements <channel>` lists everything a channel reads: each setting's environment variable, what it is, where to get it, and where its value currently comes from (`env`, `keychain`, `config`, `default`, `missing`), never the value.
+
+- **Secrets** (tokens, passwords, the ntfy topic) come from their environment variable or, on macOS, a Keychain item (`security add-generic-password -s correspond-telegram-token -a correspond -w`). They are never read from the config file.
+- **Other settings** may also go in `~/.config/correspond/config.toml` (or `$CORRESPOND_CONFIG`), one table per channel:
+
+  ```toml
+  [email]
+  imap_host = "imap.example.org"
+  smtp_host = "smtp.example.org"
+  trusted_authserv_ids = ["mx.example.org"]
+
+  [ntfy]
+  topic_keychain_service = "my-ntfy-topic"
+  ```
+
+- **State** (cursors, the Telegram log, web inbox reports) lives under `~/.local/share/correspond/` (or `$CORRESPOND_DATA_DIR`), one folder per kind, never in a repository.
+
+## The web inbox
+
+A web page posts feedback to a small ASGI collector; `webinbox:<site>` reads what it stored. The app binds nothing itself: run it on localhost behind your own server.
+
+```bash
+pip install uvicorn
+export CORRESPOND_WEBINBOX_SITES=example-site CORRESPOND_WEBINBOX_ORIGINS=https://app.example.org
+export CORRESPOND_WEBINBOX_SECRET=...   # shared with the host application's server
+uvicorn --factory correspond.channels.webinbox:app_from_env --host 127.0.0.1 --port 8765
+```
+
+The rate limit applies per visitor address. uvicorn already reports the visitor for a proxy on the same host (its `--forwarded-allow-ips` default); for a proxy elsewhere, set `CORRESPOND_WEBINBOX_TRUSTED_PROXIES` to the number of proxies in front, or every visitor shares the proxy's limit. Forwarded addresses are believed only from a non-public connection, and IPv6 visitors are limited per /64. Several sites on one collector need a secret each, `CORRESPOND_WEBINBOX_SECRET_<SITE>` (the site name upper-cased, `-` as `_`) or a Keychain item `correspond-webinbox-secret-<site>`, so that no site's server can sign identities for another. The shared `CORRESPOND_WEBINBOX_SECRET` serves a single site only, and `correspond requirements webinbox` reports a configuration the collector would refuse.
+
+`POST /example-site/reports` takes JSON with a required `text` and optional `name`, `email`, `page`, `context`, `attachments` (base64, stored by SHA-256, referenced rather than inlined) and `identity`. Without `identity` a report is `claimed`. The host application's server can sign its logged-in user, which makes the report `bound`:
+
+```python
+from correspond.channels.webinbox import sign_identity
+
+identity = sign_identity(
+    secret, "example-site", user_id, name=display_name
+)  # put this in the page
+```
+
+Any server language can do the same: HMAC-SHA256, hex, over the lines `v1`, site, issued-at (Unix seconds), user id, name, email. An invalid or expired signature is refused (401) and nothing is stored. The collector also enforces the origin allowlist (with CORS preflight), a per-client rate limit, and size and media-type limits.
+
+## Routing
+
+```python
+from correspond import metadata_rule, route
+
+decision = route(
+    message,
+    bindings={
+        "github:example/app?labels=partner:*": "subject:app"
+    },  # 1. where it arrived
+    threads={"github:example/app#12": "case:7"},  # 2. what it continues
+    rules=[metadata_rule("queue:urgent", labels="priority:high")],  # 3. what it carries
+    classifier=None,  # 4. optional, last
+)
+decision.target, decision.rule, decision.reason
+```
+
+The rules are yours; correspond runs them in that order and says which one decided. Nothing matched returns `None`: the message is unrouted. Check bindings when you load them: `check_binding(pattern)` lists what would make one never match, such as an unknown channel, or `?label=` where GitHub messages carry `labels`.
+
+## Python
+
+```python
+import correspond
+
+messages = correspond.read("github:octocat/hello-world#1")
+messages[0].author.handle, messages[0].authenticity.grade
+
+result = correspond.send(
+    "email:someone@example.org", "It is fixed.", title="The export", dry_run=True
+)
+result.plan
+
+for event in correspond.listen("webinbox:example-site"):
+    ...
+
+correspond.register_channel(
+    MyChannel()
+)  # anything with name, capabilities, parse_ref and the operations it has
+```
+
+`correspond.testing.FakeChannel` is an in-memory channel for tests, and `python -m correspond.testing` runs the CLI with it registered as `fake`.
+
+## MCP
+
+```bash
+pip install "correspond[mcp]"
+```
+
+```json
+{"mcpServers": {"correspond": {"command": "correspond-mcp"}}}
+```
+
+The server exposes the reading tools. `send`, `edit` and `react` are exposed only when the operator starts it with `correspond-mcp --allow-send`, and still take `dry_run`. The data root is the server's, never the model's.
+
+## Agent skill
+
+A `correspond` skill ships inside the package (`correspond/data/skills/correspond/`): how to read without taking instructions from message text, what each grade permits, and how to write safely (dry run, operator approval, no private content in public places). Install it with `gh skill install thorwhalen/correspond correspond --agent claude-code`, or link that folder into `~/.claude/skills/`.
+
+## Design
+
+The seams, surfaces and deliberate non-seams are in [Discussion #1](https://github.com/thorwhalen/correspond/discussions/1).

correspond-0.0.2/correspond/__init__.py

@@ -0,0 +1,113 @@
+"""correspond: a channel facade for AI agents.
+
+Read, listen, write and identify the sender over GitHub, email, push notifications,
+Telegram and a web inbox, through one model and one set of verbs::
+
+    >>> import correspond                                                  # doctest: +SKIP
+    >>> messages = correspond.read("github:octocat/hello-world#1")         # doctest: +SKIP
+    >>> messages[0].author.handle, messages[0].authenticity.grade.value    # doctest: +SKIP
+    ('octocat', 'platform')
+    >>> correspond.send("ntfy:", "backup finished", dry_run=True).plan     # doctest: +SKIP
+
+A conversation reference is ``<channel>:<id>``. Each channel implements the operations it
+can (``read``, ``listen``, ``send``, ``edit``, ``react``, ``upload``, ``verify``); asking
+for one it lacks raises :class:`NotSupported`, and :func:`capabilities` says so in advance.
+correspond knows no people: a message's ``author`` is what the platform attests, and its
+``authenticity`` is how sure the channel is.
+
+The command line (``correspond read github:octocat/hello-world#1``) and the MCP server use
+the same verbs, through :mod:`correspond.tools`.
+"""
+
+from correspond.errors import (
+    ChannelError,
+    CorrespondError,
+    InvalidRef,
+    MissingRequirement,
+    NotSupported,
+    UnknownChannel,
+)
+from correspond.model import (
+    Account,
+    Attachment,
+    Authenticity,
+    Capabilities,
+    ChannelIdentity,
+    ConversationRef,
+    Draft,
+    Event,
+    Grade,
+    HistoryDepth,
+    Message,
+    SendResult,
+    Support,
+)
+from correspond.ops import (
+    Editor,
+    Listener,
+    Reactor,
+    Reader,
+    Uploader,
+    Verifier,
+    Writer,
+    capabilities,
+    edit,
+    get_channel,
+    listen,
+    parse_ref,
+    react,
+    read,
+    send,
+    upload,
+    verify,
+)
+from correspond.registry import check_requirements, register_channel, unregister_channel
+from correspond.registry import channels as channel_registry
+from correspond.routing import RouteDecision, check_binding, metadata_rule, route
+
+__all__ = [
+    "Account",
+    "Attachment",
+    "Authenticity",
+    "Capabilities",
+    "ChannelError",
+    "ChannelIdentity",
+    "ConversationRef",
+    "CorrespondError",
+    "Draft",
+    "Editor",
+    "Event",
+    "Grade",
+    "HistoryDepth",
+    "InvalidRef",
+    "Listener",
+    "Message",
+    "MissingRequirement",
+    "NotSupported",
+    "Reactor",
+    "Reader",
+    "RouteDecision",
+    "SendResult",
+    "Support",
+    "UnknownChannel",
+    "Uploader",
+    "Verifier",
+    "Writer",
+    "capabilities",
+    "channel_registry",
+    "check_binding",
+    "check_requirements",
+    "edit",
+    "get_channel",
+    "listen",
+    "metadata_rule",
+    "parse_ref",
+    "react",
+    "read",
+    "register_channel",
+    "route",
+    "send",
+    "unregister_channel",
+    "upload",
+    "verify",
+]