From 379523e17f4f7a119564cb9ead6be1d58f1f9b20 Mon Sep 17 00:00:00 2001 From: Shane Engelman Date: Sat, 3 Oct 2026 04:35:36 -0700 Subject: [PATCH 1/3] docs: make AGENTS.md an index of the org standards Org-wide standards now live once in blacklanternsecurity/.github. This AGENTS.md states what the repo is, its toolchain and test commands, links each standard with when to read it, and keeps only what is true here and nowhere else. CLAUDE.md points at it instead of duplicating it, so agent context stops paying for restated rules. Refs blacklanternsecurity/bbot-enterprise#157 --- AGENTS.md | 41 +++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 1 + 2 files changed, 42 insertions(+) create mode 100644 AGENTS.md create mode 100644 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..712956a --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,41 @@ +# AGENTS.md + +Lightweight web screenshot tool driving a local Chrome over CDP, with DOM analysis. Used by BBOT. + +## Toolchain + +| Concern | This repository | +|---|---| +| Language | Python 3.10 through 3.14 | +| Package manager | poetry (migration to uv tracked by toolchain.md) | +| Lint and format | ruff, pinned in pyproject.toml | +| Tests | pytest | + +## Setup + +```bash +poetry install +``` + +## Tests + +```bash +poetry run pytest +``` + +## Standards + +Org-wide, in [blacklanternsecurity/.github/standards](https://github.com/blacklanternsecurity/.github/tree/main/standards). Read the one your task touches, not all of them. + +| Document | Read it when | +|---|---| +| [principles.md](https://github.com/blacklanternsecurity/.github/blob/main/standards/principles.md) | Always | +| [toolchain.md](https://github.com/blacklanternsecurity/.github/blob/main/standards/toolchain.md) | Touching dependencies, linting, formatting, or language versions | +| [git.md](https://github.com/blacklanternsecurity/.github/blob/main/standards/git.md) | Branching, commit messages, opening or reviewing a pull request | +| [rfc.md](https://github.com/blacklanternsecurity/.github/blob/main/standards/rfc.md) | A change needs agreement before work starts, or an RFC is ending | +| [testing.md](https://github.com/blacklanternsecurity/.github/blob/main/standards/testing.md) | Writing or changing tests, or anything that has them | +| [ci.md](https://github.com/blacklanternsecurity/.github/blob/main/standards/ci.md) | Touching a workflow, an action pin, or a permissions block | +| [releases.md](https://github.com/blacklanternsecurity/.github/blob/main/standards/releases.md) | Versioning, tagging, or publishing | +| [repository-setup.md](https://github.com/blacklanternsecurity/.github/blob/main/standards/repository-setup.md) | Creating a repository, or auditing one | + +Never restate a standard here. If this file and a standard disagree, the standard wins and this file is the bug. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..dc366f8 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +See @AGENTS.md. From f044010b948a9b8e7cd483fd9703c5e423639edc Mon Sep 17 00:00:00 2001 From: Shane Engelman Date: Sat, 3 Oct 2026 07:40:28 -0700 Subject: [PATCH 2/3] docs(agents): correct toolchain rows against pyproject.toml The table claimed Python 3.10 through 3.14 while pyproject.toml declares >=3.9,<3.14, called ruff pinned while it is a range, and said toolchain.md tracks a uv migration, which it does not. Reference the manifest and state plainly that the repo is not yet on uv. --- AGENTS.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 712956a..e83761c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,9 +6,9 @@ Lightweight web screenshot tool driving a local Chrome over CDP, with DOM analys | Concern | This repository | |---|---| -| Language | Python 3.10 through 3.14 | -| Package manager | poetry (migration to uv tracked by toolchain.md) | -| Lint and format | ruff, pinned in pyproject.toml | +| Language | Python, `python` in `[tool.poetry.dependencies]` of pyproject.toml | +| Package manager | poetry. Not yet on uv, see toolchain.md | +| Lint and format | ruff, version in the poetry dev group of pyproject.toml | | Tests | pytest | ## Setup From bda5058f06053efe28aa82b65ac67860cc830308 Mon Sep 17 00:00:00 2001 From: Shane Engelman Date: Sat, 3 Oct 2026 07:49:19 -0700 Subject: [PATCH 3/3] docs(agents): state the Chrome prerequisite for tests Without Chrome or Chromium on PATH, three of four tests fail with 'Chrome executable not found'. Point at possible_chrome_binaries in webcap/browser.py, which owns the list of names searched. --- AGENTS.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index e83761c..78f65d0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -19,6 +19,8 @@ poetry install ## Tests +Tests drive a real Chrome or Chromium found on PATH (`possible_chrome_binaries` in `webcap/browser.py`). Without one they fail with `Chrome executable not found`. + ```bash poetry run pytest ```