From 4b286aa64c4793b0893b7a3f300af69bf85200ce Mon Sep 17 00:00:00 2001 From: GoWithitRoger Date: Wed, 22 Jul 2026 17:11:47 -0500 Subject: [PATCH] docs: make project prose more natural --- AGENTS.md | 14 +++++++------- CONTRIBUTING.md | 4 ++-- README.md | 21 ++++++++++++--------- 3 files changed, 21 insertions(+), 18 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index c7acb44..916d170 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,14 +1,14 @@ -# Agent Guide +# Agent guide This file is for AI coding agents and automation tools working in this repository. -## Project Purpose +## Project purpose Simple Gateway Logger is a focused macOS diagnostic script for AT&T fiber gateways. It compares gateway-side diagnostics with local-machine network checks and writes each check cycle to CSV. Keep the project narrow. Do not turn it into a generic network monitoring platform, dashboard, daemon, router abstraction layer, or cross-platform framework unless explicitly asked. -## Important Files +## Important files - `main.py`: application entry point, scheduler, Selenium gateway checks, local diagnostics, CSV output. - `config.py`: user-facing runtime configuration and safety toggles. @@ -31,9 +31,9 @@ uv run pytest -q Use `uv sync` when dependencies need to be installed locally. If dependencies change, update `uv.lock`. -Prefer lint/type/tests for verification. Do not run `uv run python main.py` unless the task specifically needs live gateway or local-network behavior. +Use linting, type checks, and tests for verification. Do not run `uv run python main.py` unless the task specifically needs live gateway or local-network behavior. -## Safety And Scope +## Safety and scope - Do not commit `.env`, CSV logs, raw gateway logs, local caches, or personal network artifacts. - Treat CSV/log output as potentially sensitive because it can contain local network metadata. @@ -42,9 +42,9 @@ Prefer lint/type/tests for verification. Do not run `uv run python main.py` unle - Prefer standard-library handling for structured formats such as CSV. - Pass user-editable config values as parameters to subprocess/Selenium APIs when possible; avoid string interpolation into shell or JavaScript contexts. -## Documentation Rules +## Documentation rules -- Keep README concise and progressive: quick purpose, quickstart, common config, then optional details. +- Keep the README concise: purpose, quickstart, common config, then optional details. - Put agent-specific operational guidance here, not in the README. - Keep `main.py` script metadata dependencies in sync with `pyproject.toml`. - If behavior changes, update README, CONTRIBUTING, tests, and CI together when relevant. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5fd9925..1b9729e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,7 +1,7 @@ # Contributing Small fixes and practical improvements are welcome. For a larger change, open an issue first so we -can confirm that it fits this project's deliberately narrow scope. +can confirm that it fits this project's narrow scope. ## Setup @@ -18,5 +18,5 @@ uv run ty check uv run pytest -q ``` -Please keep changes focused, update tests or documentation when behavior changes, and do not commit +Keep changes focused, update tests or documentation when behavior changes, and do not commit `.env` files, network logs, CSV output, or other local data. diff --git a/README.md b/README.md index bee3c69..75cd0f7 100644 --- a/README.md +++ b/README.md @@ -2,12 +2,14 @@ # Simple Gateway Logger -A focused macOS diagnostic script for AT&T fiber gateways. It compares gateway-side checks with local-machine checks, then logs each check cycle to CSV so intermittent ISP, router, Wi-Fi, and client issues are easier to separate. +A macOS diagnostic script for AT&T fiber gateways. It compares checks from the gateway with +checks from the Mac and writes each cycle to CSV. This helps narrow an intermittent problem to the +ISP, router, Wi-Fi, or client. If the gateway path is healthy but the local path is not, look closer to the LAN or client device. If both degrade together, you have better evidence for an ISP-facing problem. -This is a personal hobby project maintained on a best-effort basis. It is useful for the setup it was -built around, but other gateway models and network environments may need adjustments. +I built this for my own setup and maintain it as a hobby project. Other gateway models or network +environments may need changes. ## Requirements @@ -16,7 +18,8 @@ built around, but other gateway models and network environments may need adjustm - Google Chrome for Selenium gateway checks. Selenium Manager handles ChromeDriver resolution. - Ookla's official `speedtest` CLI for local speed and under-load latency. -This is intentionally not a router-agnostic framework, dashboard, daemon, or replacement for ISP tooling. +It covers this specific workflow. It is not a router-agnostic framework, dashboard, daemon, or +replacement for ISP tooling. ## Quickstart @@ -36,7 +39,7 @@ uv run python main.py Before leaving it running, review [config.py](config.py). Optional checks such as LAN bufferbloat, raw gateway logs, stale ChromeDriver cleanup, and privileged Wi-Fi diagnostics are off by default. -## What It Logs +## What it logs - Gateway ping and optional gateway speed test. - Local WAN ping, gateway ping, Ookla speed test, jitter, packet loss, and WAN bufferbloat. @@ -81,7 +84,7 @@ CSV and raw log files can include local network metadata such as gateway latency
Optional diagnostics -### macOS Wi-Fi Metrics +### macOS Wi-Fi metrics Set `RUN_WIFI_DIAGNOSTICS_TEST = True` to collect Wi-Fi metrics using `wdutil`. The command runs with `sudo -n`, so it fails fast instead of prompting if passwordless sudo is not configured. @@ -91,7 +94,7 @@ If you choose to allow passwordless use, edit sudoers only with `sudo visudo`: your_username ALL=(ALL) NOPASSWD: /usr/bin/wdutil ``` -### LAN Bufferbloat +### LAN bufferbloat Set `RUN_LAN_BUFFERBLOAT_TEST = True` only when a second machine on your LAN is running `iperf3 -s`. @@ -102,7 +105,7 @@ iperf3 -s Then set `LAN_TEST_TARGET_IP` in [config.py](config.py) to that machine's LAN IP. -### Debug Toggles +### Debug toggles - `LOG_RAW_GATEWAY_OUTPUT`: append raw gateway ping output to `gateway_raw_output.log`. - `CLEANUP_STALE_CHROMEDRIVER_PROCESSES`: best-effort cleanup for stale ChromeDriver processes. This can terminate unrelated ChromeDriver sessions. @@ -120,7 +123,7 @@ uv run ty check uv run pytest -q ``` -See [CONTRIBUTING.md](CONTRIBUTING.md) for the small-project contribution workflow. +See [CONTRIBUTING.md](CONTRIBUTING.md) before sending a change. ## License