[Marcus778899]

Follow-up to #1, from setting Slack up against a real workspace. Two commits.

docs: add .env.example (a3c74c5)

Setting this up from the README means reading prose and remembering which steps apply to you. A template that is already the right shape removes that: copy it, delete what you do not need, fill in the rest.

cp .env.example .env

Every variable with its default, and the Slack section carries its setup steps inline — with the one everyone skips called out where it cannot be missed: inviting the bot to the channel. It also records the two traps that cost real time here:

• adding a scope needs the app reinstalled, and reinstalling issues a new token
• Slack's UI draws a channel as # common, with a space that is not part of the name

.env.example is committed while .env is gitignored, so the template can drift away from the code with nothing to catch it. Four tests stop that: every variable it names must be one the code reads, every variable the code reads must appear in it, its uncommented lines must produce a usable config, and no value in it may look like a real token. Writing them turned up that the variable names were spelled out inline in from_env, so they now come from one ENV_KEYS mapping used by both the loader and the tests.

The README also gains an appendix, the bot must be in the channel — the most common reason a correct-looking setup delivers nothing — with a table separating not_in_channel from channel_not_found, missing_scope, invalid_auth and is_archived.

fix: degrade on bad Slack settings (89ed739)

A misconfigured optional notifier could stop the program from logging. A malformed credential raised out of the first log call and killed the process. The handler already refuses to let a dead webhook do that, so a typo in the same feature should not either.

Slack is now switched off and the reason written once at CRITICAL:

Slack alerts are disabled: SLACK_BOT_TOKEN does not look like a bot token; it
should start with 'xoxb-'. The Basic Information page has no bot token on it --
find it under OAuth & Permissions -> Bot User OAuth Token

log_dir and level still raise — there is nothing sensible to fall back to there. LoggerConfig.slack_problem() is the check, and credentials never appear in it.

Setting names are checked by Logger() and configure() rather than where they are resolved. Resolution is lazy, so configure(load_env=True) used to fail at the first log call, with a traceback pointing at a line that was perfectly correct. Near misses are now suggested:

ConfigError: unknown setting(s): 'load_env' (did you mean 'load_dotenv'?)

chat.postMessage payloads carry a top-level text as well as the attachment. Without it the push notification and sidebar preview arrive blank.

Comments are also gone from the source, with the two load-bearing ones folded into docstrings: the stacklevel offset (a wrapper added above _emit would silently point origin at logger.py) and why the bot-token path reads the response body.

Verification

• 161 tests on Python 3.8, 3.9 and 3.12
• pre-commit run --all-files clean; uv build produces a wheel that imports from a clean environment
• Every code example in the README executed
• Alerts confirmed arriving in a real Slack channel

🤖 Generated with Claude Code