irc-lens 0.1.0__tar.gz

irc_lens-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,47 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      - uses: astral-sh/setup-uv@38f3f104447c67c051c4a08e39b64a148898af3a # v4
+
+      - run: uv python install 3.12
+
+      - run: uv venv
+
+      - run: uv pip install -e ".[dev]"
+
+      - name: pytest
+        run: uv run pytest -v
+
+  playwright:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      - uses: astral-sh/setup-uv@38f3f104447c67c051c4a08e39b64a148898af3a # v4
+
+      - run: uv python install 3.12
+
+      - run: uv venv
+
+      - run: uv pip install -e ".[dev]"
+
+      - name: Install chromium for pytest-playwright
+        run: uv run playwright install --with-deps chromium
+
+      - name: pytest -m playwright
+        run: uv run pytest -m playwright -v

irc_lens-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,114 @@
+name: Publish to PyPI
+
+# PR → TestPyPI (`.devN` build, `testpypi` environment).
+# push to main → PyPI (`x.y.z` build, `pypi` environment).
+#
+# The path filter keeps doc-only PRs from churning TestPyPI; bumps to
+# the workflow itself still trigger so changes get validated before
+# they land. Trusted-publishing means no long-lived tokens — both
+# environments are pre-provisioned with PyPI Trusted Publishers
+# pointing at this repo.
+
+on:
+  push:
+    branches: [main]
+    # Push triggers `publish` against PyPI, which rejects re-uploads of
+    # an existing version. Gate it on `pyproject.toml` so the publish
+    # only fires when `[project] version` bumps. `src/**` changes still
+    # run on PRs (test-publish) and are validated by `ci.yml`'s `test`
+    # job on push to main; we just don't try to re-publish them.
+    paths:
+      - "pyproject.toml"
+      - ".github/workflows/publish.yml"
+  pull_request:
+    branches: [main]
+    # PRs are safe to run on broader changes — `test-publish` mints a
+    # unique `.devN` per run_number so re-uploads can't collide.
+    paths:
+      - "pyproject.toml"
+      - "src/**"
+      - ".github/workflows/publish.yml"
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      - uses: astral-sh/setup-uv@38f3f104447c67c051c4a08e39b64a148898af3a # v4
+
+      - run: uv python install 3.12
+
+      - run: uv venv
+
+      - run: uv pip install -e ".[dev]"
+
+      - name: pytest
+        run: uv run pytest -v
+
+  test-publish:
+    if: github.event_name == 'pull_request'
+    needs: test
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      - uses: astral-sh/setup-uv@38f3f104447c67c051c4a08e39b64a148898af3a # v4
+
+      - run: uv python install 3.12
+
+      - name: Mint dev version
+        # Trusted-publishing won't accept the same version twice, so
+        # every PR build needs a unique suffix. `github.run_number` is
+        # monotonic per workflow file and survives re-runs of the same
+        # workflow run (those reuse the run_attempt, not run_number).
+        # Use the uv-installed 3.12 interpreter explicitly so this step
+        # doesn't depend on whatever `python` the runner happens to
+        # ship (tomllib is 3.11+).
+        run: |
+          BASE=$(uv run --python 3.12 python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          DEV_VERSION="${BASE}.dev${{ github.run_number }}"
+          sed -i "s/^version = .*/version = \"${DEV_VERSION}\"/" pyproject.toml
+          echo "DEV_VERSION=${DEV_VERSION}" >> "$GITHUB_ENV"
+          echo "Publishing ${DEV_VERSION} to TestPyPI"
+
+      - name: Build and publish to TestPyPI
+        run: |
+          uv build
+          uv publish \
+            --publish-url https://test.pypi.org/legacy/ \
+            --trusted-publishing always \
+            --check-url https://test.pypi.org/simple/
+
+      - name: Print install command
+        if: always()
+        run: |
+          echo "::notice::Test with: pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ irc-lens==${DEV_VERSION}"
+
+  publish:
+    if: github.event_name == 'push'
+    needs: test
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      - uses: astral-sh/setup-uv@38f3f104447c67c051c4a08e39b64a148898af3a # v4
+
+      - run: uv python install 3.12
+
+      - name: Build and publish to PyPI
+        run: |
+          uv build
+          uv publish \
+            --trusted-publishing always \
+            --check-url https://pypi.org/simple/

irc_lens-0.1.0/.gitignore

@@ -0,0 +1,225 @@
+# 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
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# 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/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# Cited references from afi cli cite (regenerate locally; never committed)
+.afi/
+
+# Per-user Claude Code config (settings, scheduled tasks, project-local
+# skills, etc. — none of these belong in the repo).
+.claude/

irc_lens-0.1.0/CITATION.md

@@ -0,0 +1,23 @@
+# Citation
+
+`irc-lens` follows Culture's **cite-don't-import** rule. Cited code is
+copied (and adapted) from upstream sources, then carried in this repo as
+its own source. We track the upstream commit each file was lifted from
+so future updates can be diffed against it deliberately.
+
+## Sources
+
+| Local path | Source repo | Source path | Source SHA | Adaptation |
+| --- | --- | --- | --- | --- |
+| `src/irc_lens/irc/buffer.py` | `agentculture/culture` | `packages/agent-harness/message_buffer.py` | `57d3ba8` | One additive divergence: `MessageBuffer.add` accepts an optional `timestamp: float \| None = None` (defaults to `time.time()` when omitted, preserving upstream behaviour for every existing caller). The Phase 8 `--seed` loader uses this to preload fixture messages with fixed clocks so Playwright tests can assert on stable timestamps without reaching into `_buffers`. Safe to upstream. |
+| `src/irc_lens/irc/message.py` | `agentculture/culture` | `culture/protocol/message.py` | `57d3ba8` | Byte-faithful copy. The IRC line parser is shared by every AgentIRC client; the lens needs it to decode wire bytes in the read loop. |
+| `src/irc_lens/irc/transport.py` | `agentculture/culture` | `packages/agent-harness/irc_transport.py` | `57d3ba8` | Imports rewired to `irc_lens.irc.*`; `culture.aio.maybe_await` inlined as `_maybe_await` (3 lines). **`CAP REQ :message-tags` removed** per the spec — the lens doesn't render IRCv3 tags (precedent: `culture/console/client.py:50-55`). **All telemetry/OTEL infrastructure removed** — the `_span` helper, the `tracer`/`metrics`/`backend` constructor kwargs, the traceparent injection in `send_raw`, and the inbound traceparent extraction in `_handle`. The lens has no agent loop and the spec excludes telemetry. Persistent-connection + read-loop shape preserved. `system-` event filter retained. **`add_listener(command, cb)` added** so `Session` can observe inbound PRIVMSG/JOIN/PART without replacing the buffer-add handlers in `_cmd_handlers` — the dict has one slot per command and the existing handlers do load-bearing work; chaining via a parallel listener list keeps both responsibilities additive (Phase 5). Listeners run after the primary handler; exceptions are logged + swallowed so a misbehaving observer can't break the read loop. **Two upstream bug-fixes + one minor improvement carried (flag for back-port to culture):** (a) `disconnect()` now catches `OSError` on `wait_closed()` instead of just `ConnectionError`, matching the QUIT-send handling above it (`ConnectionResetError` is one of several transport errors that can raise from `wait_closed`). (b) `_read_loop` now buffers as bytes and decodes per complete line; per-chunk `decode("utf-8", errors="replace")` corrupts multibyte sequences split across `recv` boundaries with U+FFFD. (c) `_reconnect` now wraps the retry loop in `try/finally` so `self._reconnecting` is released even if the loop exits because `_should_run` flipped or an unexpected exception escapes — upstream only releases the gate on successful return, so the gate could leak. The `except OSError:` itself is unchanged from upstream and correct: `ConnectionError` (which `_do_connect` raises) is a subclass of `OSError` in Python 3.3+, so the bare `OSError` catch handles it. |
+| `src/irc_lens/commands.py` | `agentculture/culture` | `culture/console/commands.py` | `57d3ba8` | Byte-faithful copy. |
+
+## Refresh
+
+To refresh a cited file against a newer upstream, diff the new upstream
+against the source SHA recorded above, port intentional changes, and
+update the SHA in this table. Do not just overwrite — culture's
+`packages/agent-harness` and `culture/console` evolve together with
+agent-runtime concerns that `irc-lens` does not need.

irc_lens-0.1.0/CLAUDE.md

@@ -0,0 +1,88 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this repo is
+
+`irc-lens` is the lens CLI for **AgentIRC** in the **Culture** ecosystem (a sibling repo named `culture` — typically checked out alongside this one). The repo is a fresh skeleton — at the time of writing there is no source code yet. Tracked files at the top level:
+
+- `README.md` — one-line purpose statement.
+- `LICENSE` — project license.
+- `CLAUDE.md` — this file.
+- `.gitignore` — standard Python ignores plus `.afi/` and `.claude/settings.local.json`.
+
+Not tracked, but expected to exist locally:
+
+- `.afi/reference/python-cli/` — generated by `afi cli cite python-cli` (see next section). Cited, not imported; ignored by git on purpose.
+- `.claude/settings.local.json` — per-user Claude Code settings (allowlist etc.). Local-only.
+
+The first non-trivial task in this repo will be to bootstrap the Python package by integrating the `.afi/reference/python-cli/` pattern. Generate that pattern locally and read it *before* writing any CLI scaffolding from scratch.
+
+## The `.afi/reference/python-cli/` reference (regenerate locally before reading)
+
+This reference is **not committed**. It is produced on demand by `afi cli cite` (from the `citation-cli` / formerly `assimilai` project — typically a sibling checkout). Regenerate it with:
+
+```bash
+afi cli cite python-cli       # writes .afi/reference/python-cli/
+```
+
+If `afi` isn't on your `PATH`, follow the install instructions in the `citation-cli` repo. Once `.afi/reference/python-cli/AGENT.md` and `MANIFEST.json` exist locally, defer to them — they are the authoritative spec for the **agent-first Python CLI** pattern this project conforms to. The summary below is just orientation; if it ever conflicts with the cited material, the cited material wins.
+
+### Token substitution
+
+`{{project_name}}`, `{{slug}}`, `{{module}}` are placeholders. They are **not** substituted in the reference itself — substitute them when you copy a file into the host package. For this repo the natural choices are:
+
+- `{{project_name}}` → `irc-lens`
+- `{{slug}}` / `{{module}}` → `irc_lens`
+
+### File roles
+
+`MANIFEST.json` tags each file as `stable-contract` or `shape-adapt`:
+
+- **`stable-contract`** — copy verbatim, then token-substitute. Don't reshape unless the host already has equivalents. Covers `cli/_errors.py` (`AfiError`, exit codes), `cli/_output.py` (stdout/stderr split, `--json`), `cli/_commands/explain.py`, and `explain/` (catalog resolver).
+- **`shape-adapt`** — keep the structure, rewrite the content for the host tool. Covers `cli/__init__.py` (parser + `_dispatch`, including the `_ArgumentParser` override and try/except), `cli/_commands/learn.py` (TEXT body + JSON payload), `explain/catalog.py`, the package `__init__.py` / `__main__.py`, and `tests/test_cli.py`.
+
+### Hard contracts to preserve
+
+These are checked by `afi cli verify` and must not be weakened when shape-adapting:
+
+1. **Exit-code policy** — `0` success, `1` user error, `2` env error, `3+` reserved. All failures raise `AfiError`; the dispatcher catches and exits with `err.code`. No Python traceback ever leaks.
+2. **stdout/stderr split** — results to stdout, errors and diagnostics to stderr, even in `--json` mode. The streams are never mixed.
+3. **Errors have shape `{code, message, remediation}`** — text-mode errors render as `error: <msg>\nhint: <remediation>`. The `hint:` prefix is required by the rubric.
+4. **`_ArgumentParser` override** — argparse errors must route through `emit_error` so unknown verbs/flags exit with `error:` + `hint:` and no traceback.
+5. **Globals `learn`, `explain`, `overview` exist at the top level** — not nested under a noun. New command groups are registered as siblings via `register(sub)` in `cli/__init__.py` at the marked location. Every noun group with action-verbs must also expose its own `overview` verb.
+6. **`learn` output rubric** — stdout ≥ 200 chars, mentions purpose, commands, exit codes, `--json`, and `explain`. `learn --json` is parseable with stderr clean.
+7. **`overview` is descriptive, not verifying** — `overview <bogus-path>` exits **0** with a warning section. Hard-failing on a missing target is `afi cli verify`'s job, not `overview`'s.
+
+### `afi cli verify` rubric bundles
+
+The six bundles checked by the verifier (run from the host project root once code exists):
+
+1. **Structure** — `pyproject.toml` with `[project.scripts]`, `tests/` dir, `<tool> --help` exits 0.
+2. **Learnability** — `<tool> learn` exits 0, stdout ≥ 200 chars, mentions purpose / commands / exit codes / `--json` / `explain`.
+3. **JSON** — `<tool> learn --json` parseable; stderr clean on success; `<tool> explain --json` works.
+4. **Errors** — bogus verb exits non-zero with a `hint:` line and no Python traceback.
+5. **Explain** — `explain`, `explain <tool>`, and bogus-path-failure with hint all work.
+6. **Overview** — global `<tool> overview` exits 0; `<tool> overview --json` returns `{subject, path, sections}`; every noun group with action-verbs also exposes an `overview` verb (e.g. `<tool> cli overview`); `<tool> overview <bogus-path>` exits **0** with a warning section (overview is descriptive, not verifying).
+
+The `python-cli` reference template predates the `overview` bundle. The bootstrap phase explicitly adds an `overview` global + a minimal `cli` noun with `cli overview`. New noun groups added later must follow the same rule.
+
+After integration completes and the rubric passes, the reference can be removed (`rm -rf .afi/reference/`) or refreshed with `afi cli cite`.
+
+## Workspace context (Culture / AgentIRC)
+
+In this workspace's standard layout, `irc-lens` is checked out alongside `culture` and `citation-cli` as sibling directories. The exact location varies by contributor; what matters is the relationship, not the absolute path. Worth knowing when scoping changes:
+
+- **Culture** is an IRC-based agent mesh; AgentIRC is the protocol/IRCd component. `irc-lens` is its **lens** CLI — read-only-ish observability/inspection tooling, by name. Confirm exact scope against the parent project before adding write paths.
+- **citation-cli** (`afi`) provided the `.afi/reference/` here. The pattern is *cited, not imported* — this project owns its copy and may modify it, but divergences from the rubric should be deliberate.
+- **All-backends rule** (Culture): if a feature lands on one agent backend (`claude` / `codex` / `copilot` / `acp`), it must be propagated to all of them. If `irc-lens` grows backend-aware code, that rule applies here too.
+
+## Tooling expectations once code exists
+
+If a workspace-level `CLAUDE.md` is present in the parent directory of your checkouts, it sets the defaults. None of this is enforced *yet* because there's no code, but the next contributor should expect:
+
+- **`uv`** for dependency management: `uv venv && uv pip install -e ".[dev]"`, then `pytest`.
+- **Linting**: `flake8`, `pylint`, `bandit -r src/`, `black`, `isort`. Markdown via `markdownlint-cli2`.
+- **Versioning**: a single source of truth in `pyproject.toml` / `irc_lens/__init__.py`. Bump before PRs.
+
+When wiring `pyproject.toml`, register the CLI under `[project.scripts]` as `irc-lens = "irc_lens.cli:main"` (matching the reference's `cli.main`).

irc_lens-0.1.0/LICENSE

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

irc_lens-0.1.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: irc-lens
+Version: 0.1.0
+Summary: Reactive web console for AgentIRC — Playwright-driveable lens for the Culture mesh.
+Project-URL: Homepage, https://github.com/agentculture/irc-lens
+Project-URL: Issues, https://github.com/agentculture/irc-lens/issues
+Author-email: Ori Nachum <ori.nachum@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 agentculture
+        
+        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.
+License-File: LICENSE
+Keywords: agent,agentirc,console,culture,htmx,irc,lens,sse
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Chat :: Internet Relay Chat
+Requires-Python: >=3.11
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: jinja2>=3.1
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: playwright>=1.40; extra == 'dev'
+Requires-Dist: pytest-aiohttp>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest-playwright>=0.5; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# irc-lens
+
+`irc-lens` is the agent-driven web console for **AgentIRC** in the
+[Culture](https://github.com/agentculture/culture) ecosystem. Where
+the existing Textual TUI requires a human at a terminal,
+`irc-lens` re-implements the same console as a localhost aiohttp
+app (HTMX + SSE, server-rendered fragments) so a Playwright agent
+or human browser can drive it deterministically.
+
+## Quickstart
+
+```bash
+pip install irc-lens
+irc-lens serve --host 127.0.0.1 --port 6667 --nick lens --open
+```
+
+The `--open` flag launches the default browser at the printed
+URL. Quit with Ctrl-C.
+
+## Develop
+
+```bash
+git clone https://github.com/agentculture/irc-lens && cd irc-lens
+uv venv && uv pip install -e ".[dev]"
+uv run pytest -v                         # default suite
+uv run playwright install chromium       # one-time
+uv run pytest -m playwright -v           # browser e2e
+```
+
+## Docs
+
+* [`docs/cli.md`](docs/cli.md) — every flag, exit code, the
+  `--seed` schema.
+* [`docs/slash-commands.md`](docs/slash-commands.md) — verb table
+  (`/join`, `/help`, `/send`, …).
+* [`docs/sse-events.md`](docs/sse-events.md) — SSE event catalogue,
+  fragment templates, `data-testid` contract.
+* [`docs/playwright.md`](docs/playwright.md) — driving the lens
+  with pytest-playwright or Playwright MCP.
+* [`docs/architecture.md`](docs/architecture.md) — runtime
+  topology, module layout, decision log.
+* [`CITATION.md`](CITATION.md) — culture citations + divergences.
+
+## License
+
+See [LICENSE](LICENSE).

irc_lens-0.1.0/README.md

@@ -0,0 +1,46 @@
+# irc-lens
+
+`irc-lens` is the agent-driven web console for **AgentIRC** in the
+[Culture](https://github.com/agentculture/culture) ecosystem. Where
+the existing Textual TUI requires a human at a terminal,
+`irc-lens` re-implements the same console as a localhost aiohttp
+app (HTMX + SSE, server-rendered fragments) so a Playwright agent
+or human browser can drive it deterministically.
+
+## Quickstart
+
+```bash
+pip install irc-lens
+irc-lens serve --host 127.0.0.1 --port 6667 --nick lens --open
+```
+
+The `--open` flag launches the default browser at the printed
+URL. Quit with Ctrl-C.
+
+## Develop
+
+```bash
+git clone https://github.com/agentculture/irc-lens && cd irc-lens
+uv venv && uv pip install -e ".[dev]"
+uv run pytest -v                         # default suite
+uv run playwright install chromium       # one-time
+uv run pytest -m playwright -v           # browser e2e
+```
+
+## Docs
+
+* [`docs/cli.md`](docs/cli.md) — every flag, exit code, the
+  `--seed` schema.
+* [`docs/slash-commands.md`](docs/slash-commands.md) — verb table
+  (`/join`, `/help`, `/send`, …).
+* [`docs/sse-events.md`](docs/sse-events.md) — SSE event catalogue,
+  fragment templates, `data-testid` contract.
+* [`docs/playwright.md`](docs/playwright.md) — driving the lens
+  with pytest-playwright or Playwright MCP.
+* [`docs/architecture.md`](docs/architecture.md) — runtime
+  topology, module layout, decision log.
+* [`CITATION.md`](CITATION.md) — culture citations + divergences.
+
+## License
+
+See [LICENSE](LICENSE).