Skip to content

Fix docs accuracy + two real bugs found while verifying them - #2

Merged
klept0 merged 1 commit into
mainfrom
fix/docs-accuracy-and-dashboard-bugs
Jul 1, 2026
Merged

klept0 merged 1 commit into
mainfrom
fix/docs-accuracy-and-dashboard-bugs

Conversation

@klept0

@klept0 klept0 commented Jul 1, 2026

Copy link
Copy Markdown
Owner

Summary

Follow-up to #1 (merged). While confirming the README/CHANGELOG were up to date against the current code, found and fixed two real functional bugs, plus corrected several stale doc claims:

Bugs found while verifying docs:

  • web/app.py's home page 500'd on every load (TypeError: cannot use 'tuple' as a dict key) — templates.TemplateResponse("index.html", {"request": request}) is the old, removed Starlette calling convention on the pinned version. Fixed to TemplateResponse(request, "index.html").
  • The dashboard's own frontend called every /api/* endpoint with a bare fetch(), so the X-API-Key auth requirement added in Fix broken reply-history mapping; harden web dashboard #1 broke the built-in UI (401 on every button and the initial status load). Added an apiFetch() wrapper that prompts for the key once, stores it in localStorage, and re-prompts on 401. Verified the full flow live (200 with correct key, 401 + cleared storage on wrong key).
  • python-dotenv was a declared dependency that nothing ever called — cp .env.example .env had no effect on a plain python web/app.py run. Added load_dotenv() on startup.

Docs corrected:

  • All three install paths said to "edit .env with your Telegram API credentials" — .env only ever holds web-dashboard settings; credentials are entered interactively and stored in resources/credentials.json. Corrected each path and noted the web dashboard/Docker web service need a session from running python main.py once first.
  • ## Changelog Policy sat between two subsections of ## Usage, making ### Web API read as its child. Moved it under ## Contributing, restored ### Web API under ## Usage, documented the X-API-Key requirement there.
  • Added docs/ and tests/ to the project tree, plus "Running Tests and Checks" / "Building Documentation" subsections matching what CI actually runs.

Test plan

  • ruff check / ruff format --check — clean
  • mypy source/ web/app.py — clean
  • pytest tests/ — 16/16 pass
  • Verified the dashboard live via a preview server: page loads (200, no more 500), apiFetch correctly attaches X-API-Key (200 with correct key, 401 + key cleared on wrong key)

Asked to confirm README/CHANGELOG are up to date; while checking each
claim against the actual code, found and fixed two functional bugs:

- web/app.py's home page 500'd on every load (TypeError: cannot use
  'tuple' as a dict key) — templates.TemplateResponse("index.html",
  {"request": request}) is the old, removed Starlette calling
  convention on the pinned starlette version. Fixed to
  TemplateResponse(request, "index.html").
- The dashboard's own frontend called every /api/* endpoint with a
  bare fetch(), so the X-API-Key requirement added in the previous
  round of fixes broke the built-in UI (401 on every button and the
  initial status load). Added an apiFetch() wrapper that prompts for
  the key once, stores it in localStorage, and re-prompts on 401.
  Verified the full flow (200 with correct key, 401 + cleared storage
  on wrong key) via a live preview server.
- python-dotenv was declared as a dependency but never actually
  loaded, so `cp .env.example .env` silently did nothing for a plain
  `python web/app.py` run (only docker-compose substitutes .env).
  Added load_dotenv() on startup.

Then fixed what was actually stale in the docs:

- All three install paths in README told users to "edit .env with
  your Telegram API credentials" — .env only ever holds web-dashboard
  settings (API_KEY/WEB_HOST/WEB_PORT); credentials are entered
  interactively and stored in resources/credentials.json. Corrected
  each path and added notes that the web dashboard / Docker web
  service need a session created by running `python main.py` once.
- `## Changelog Policy` sat between two subsections of `## Usage`,
  making `### Web API` read as its child. Moved it under
  `## Contributing`, restored `### Web API` under `## Usage`, and
  documented the new X-API-Key requirement there.
- Added docs/ and tests/ to the project tree, plus "Running Tests and
  Checks" and "Building Documentation" subsections matching what CI
  actually runs.

Co-Authored-By: Claude <noreply@anthropic.com>
@klept0
klept0 merged commit f817e4b into main Jul 1, 2026
7 checks passed
@klept0
klept0 deleted the fix/docs-accuracy-and-dashboard-bugs branch July 1, 2026 02:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant