Skip to content

chore: staging 0.34.5rc3 — docs screenshots + bug fixes#130

Merged
Nathan Schram (nathanschram) merged 22 commits intomasterfrom
feature/github-hardening
Mar 14, 2026
Merged

chore: staging 0.34.5rc3 — docs screenshots + bug fixes#130
Nathan Schram (nathanschram) merged 22 commits intomasterfrom
feature/github-hardening

Conversation

@nathanschram
Copy link
Copy Markdown
Member

@nathanschram Nathan Schram (nathanschram) commented Mar 14, 2026

Summary

  • Screenshots: 44 JPG screenshots integrated across 25 doc files, hero collage for README (voice → approval → parallel projects), HTML <img> tags for GitHub/MkDocs compatibility
  • Bug fix: EngineOverrides field preservation — setting model/planmode/reasoning no longer silently wipes ask_questions, diff_preview, show_api_cost, etc.
  • Bug fix: /config home page resolves "default" to effective values (e.g. "default" ask mode shows as "on")
  • Feature: File upload auto-deduplication (append _1, _2 instead of requiring --force)
  • Feature: Media groups without captions now auto-save instead of showing usage text
  • Feature: Resume line visual separation (blank line + ↩️ prefix)
  • Fix: Claude auto-approve echoes updatedInput in control response
  • CI: CODEOWNERS, action SHA pins, release guard hooks
  • Fix: CI release-validation tomllib bytes/str mismatch
  • Feature: CPU-active stall suppression + heartbeat re-render

Test plan

  • uv run pytest — 1567 passed, 81% coverage
  • uv run ruff check src/ — clean
  • Nathan merges → TestPyPI publish (automatic, no reviewer)
  • scripts/staging.sh install 0.34.5rc3 on staging bot
  • Dogfood on @hetz_lba1_bot

No PyPI main publish. No tags, no changelog entry. rc version only.

🤖 Generated with Claude Code

Summary by CodeRabbit

  • New Features

    • Added About page displaying Untether version, engine versions, and helpful links.
    • Automatic file deduplication: uploading files with duplicate names now creates numbered copies instead of failing.
  • UI/UX Improvements

    • Enhanced resume line display with visual separator and arrow icon.
    • Reorganized home page; version information moved to About page.
    • Settings now display effective default values clearly.
  • Documentation

    • Expanded visual documentation with screenshots and asset guides across all feature guides.

- Create .github/CODEOWNERS requiring @littlebearapps/core review
- Pin setup-uv to v7.4.0 (6ee6290f), download-artifact to v8.0.1 (3e5f45b2)
- Add precise version comments on all action SHAs (codeql v3.32.6,
  pypi-publish v1.13.0, action-gh-release v2.5.0, fetch-metadata v2.5.0)
- Document write permissions with why-comments (OIDC, releases, auto-merge)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Defence-in-depth hooks prevent Claude Code from pushing to master,
merging PRs, creating tags, or triggering releases. Feature branch
pushes and PR creation remain allowed.

- release-guard.sh: Bash hook blocking master push, tags, releases, PR merge
- release-guard-protect.sh: Edit/Write hook protecting guard files and hooks.json
- release-guard-mcp.sh: GitHub MCP hook blocking merge and master writes
- hooks.json: register all three hooks
- CLAUDE.md: document release guard, update workflow roles, CI pipeline notes

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
… lines

Default labels now explain what "default" means for each setting:
- Diff preview: "default (off)" — matches actual behaviour (was "default (on)")
- Model/Reasoning: "default (engine decides)"
- API cost: "default (on)", Subscription usage: "default (off)"
- Plan mode home hint: "agent decides"
- Diff preview home hint: "buttons only"

Added info lines to plan mode and reasoning sub-pages explaining
the default behaviour in more detail.

Removed all 9 "Works with: ..." lines from sub-pages — they're
redundant because engine visibility guards already hide settings
from unsupported engines.

Fixes #119

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
When a run fails (e.g. subscription limit hit), the diagnostic context
line from _extract_error() already shows cost, turns, and API time.
The 💰 cost footer was duplicating this same data in a different format.

Now the cost footer only appears on successful runs where it's the sole
source of cost information. Error runs still show cost in the diagnostic
line, and budget alerts still fire regardless.

Also adds usage field to mock Return dataclass (matching ErrorReturn)
so tests can verify cost footer behaviour on success runs.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
When cpu_active=True (extended thinking, background agents), suppress
Telegram stall warning notifications and instead trigger a heartbeat
re-render so the elapsed time counter keeps ticking. Notifications
still fire when cpu_active=False or None (no baseline).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
tomllib.loads() expects str but was receiving bytes from
sys.stdin.buffer.read() and open(...,'rb').read(). First
triggered when PR #122 changed the version (rc1 → rc2).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Add 44 screenshots to docs/assets/screenshots/
- Fix all image refs from .png to .jpg across 25 doc files
- README uses absolute raw.githubusercontent.com URLs for PyPI rendering
- Fix 5 filename mismatches (session-auto-resume→chat-auto-resume, etc.)
- Comment out 11 missing screenshots with TODO markers
- Add CAPTURES.md checklist tracking capture status

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Switch from MkDocs `![alt](src){ loading=lazy }` syntax to HTML `<img>`
tags with width="360" and loading="lazy". Fixes two GitHub rendering
issues: `{ loading=lazy }` appearing as visible text, and oversized
images with no width constraint.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- first-run.md: rewrite resume line text to match footer screenshot
- interactive-control.md: update planmode show admonition to match screenshot (auto not on)
- switch-engines.md: swap engine-footer.jpg for multi-engine-switch.jpg
- Replace startup-message.jpg with clean v0.34.4 capture (was rc/6-projects)
- Replace cooldown-auto-deny.jpg with post-outline approve/deny buttons
- Replace file-put.jpg with photo save confirmation

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Telegram iOS doesn't show a caption field when sending documents via the
File picker, so /file put <path> captions aren't easily accessible.
Added a note with workarounds (use Desktop, send as photo, or let
auto-save handle it). Updated screenshot alt text to match actual
screenshot content.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Will revert to master before merging.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Reduce from 360px to 270px each and combine into one <p> block
so all three hero screenshots sit side by side.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Replace plan-outline-approve (too similar to approval-diff-preview)
with config-menu showing the /config settings grid. The three hero
images now tell: voice input → approve changes → configure everything.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Small <sub> captions: "Send tasks by voice (Whisper transcription)",
"Approve changes remotely", "Configure from Telegram".

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Fixes stacking issue — <br> in a <p> broke inline flow. A table
keeps images side by side with captions underneath each one.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Composite image scales proportionally on mobile instead of requiring
horizontal scroll. Captions baked into the image via ImageMagick.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Replace approval-diff-preview with approval-buttons-howto showing
Approve / Deny / Pause & Outline Plan — more visually impressive.
Caption now reads "Approve changes remotely (Claude Code)".
Added footnote linking to engine compatibility table.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Third hero screenshot now shows 10+ projects running simultaneously
across different repos — much more compelling than a settings menu.
New caption: "Run agents across projects in parallel".

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Swap hero-collage URL back from feature/github-hardening to master.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- fix: preserve all EngineOverrides fields when setting model/planmode/reasoning
  (was silently wiping ask_questions, diff_preview, show_api_cost, etc.)
- fix: /config home page resolves "default" to effective values
- feat: file upload auto-deduplication (append _1, _2 instead of requiring --force)
- feat: media groups without captions now auto-save instead of showing usage text
- feat: resume line visual separation (blank line + ↩️ prefix)
- fix: claude auto-approve echoes updatedInput in control response

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@coderabbitai
Copy link
Copy Markdown

coderabbitai bot commented Mar 14, 2026

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 937457fe-2ada-4dab-b628-55addc0aae6d

📥 Commits

Reviewing files that changed from the base of the PR and between c96a7bc and 2e32b7e.

⛔ Files ignored due to path filters (47)
  • docs/assets/screenshots/agent-resolution.jpg is excluded by !**/*.jpg
  • docs/assets/screenshots/approval-buttons-howto.jpg is excluded by !**/*.jpg
  • docs/assets/screenshots/approval-diff-preview.jpg is excluded by !**/*.jpg
  • docs/assets/screenshots/ask-question-options-alt.jpg is excluded by !**/*.jpg
  • docs/assets/screenshots/ask-question-options.jpg is excluded by !**/*.jpg
  • docs/assets/screenshots/ask-reply-continue.jpg is excluded by !**/*.jpg
  • docs/assets/screenshots/ask-reply-sent.jpg is excluded by !**/*.jpg
  • docs/assets/screenshots/ask-text-reply-howto.jpg is excluded by !**/*.jpg
  • docs/assets/screenshots/browse-directory.jpg is excluded by !**/*.jpg
  • docs/assets/screenshots/cancel-button.jpg is excluded by !**/*.jpg
  • docs/assets/screenshots/chat-auto-resume.jpg is excluded by !**/*.jpg
  • docs/assets/screenshots/compact-progress.jpg is excluded by !**/*.jpg
  • docs/assets/screenshots/config-menu.jpg is excluded by !**/*.jpg
  • docs/assets/screenshots/cooldown-auto-deny.jpg is excluded by !**/*.jpg
  • docs/assets/screenshots/cost-warning-alert.jpg is excluded by !**/*.jpg
  • docs/assets/screenshots/deny-response.jpg is excluded by !**/*.jpg
  • docs/assets/screenshots/engine-footer.jpg is excluded by !**/*.jpg
  • docs/assets/screenshots/exit-planmode-buttons.jpg is excluded by !**/*.jpg
  • docs/assets/screenshots/export-transcript.jpg is excluded by !**/*.jpg
  • docs/assets/screenshots/file-get.jpg is excluded by !**/*.jpg
  • docs/assets/screenshots/file-put-alt.jpg is excluded by !**/*.jpg
  • docs/assets/screenshots/file-put.jpg is excluded by !**/*.jpg
  • docs/assets/screenshots/file-transfer-media.jpg is excluded by !**/*.jpg
  • docs/assets/screenshots/final-answer-footer-alt.jpg is excluded by !**/*.jpg
  • docs/assets/screenshots/final-answer-footer-alt2.jpg is excluded by !**/*.jpg
  • docs/assets/screenshots/final-answer-footer.jpg is excluded by !**/*.jpg
  • docs/assets/screenshots/hero-collage.jpg is excluded by !**/*.jpg
  • docs/assets/screenshots/hero-voice-to-result.jpg is excluded by !**/*.jpg
  • docs/assets/screenshots/multi-engine-switch.jpg is excluded by !**/*.jpg
  • docs/assets/screenshots/new-session-clear.jpg is excluded by !**/*.jpg
  • docs/assets/screenshots/parallel-projects.jpg is excluded by !**/*.jpg
  • docs/assets/screenshots/plan-outline-approve.jpg is excluded by !**/*.jpg
  • docs/assets/screenshots/plan-outline-text.jpg is excluded by !**/*.jpg
  • docs/assets/screenshots/planmode-auto.jpg is excluded by !**/*.jpg
  • docs/assets/screenshots/planmode-on.jpg is excluded by !**/*.jpg
  • docs/assets/screenshots/planmode-show.jpg is excluded by !**/*.jpg
  • docs/assets/screenshots/post-outline-buttons.jpg is excluded by !**/*.jpg
  • docs/assets/screenshots/progress-streaming.jpg is excluded by !**/*.jpg
  • docs/assets/screenshots/project-command.jpg is excluded by !**/*.jpg
  • docs/assets/screenshots/startup-message.jpg is excluded by !**/*.jpg
  • docs/assets/screenshots/stateless-reply-resume.jpg is excluded by !**/*.jpg
  • docs/assets/screenshots/stateless-resume-line.jpg is excluded by !**/*.jpg
  • docs/assets/screenshots/usage-command.jpg is excluded by !**/*.jpg
  • docs/assets/screenshots/verbose-on.jpg is excluded by !**/*.jpg
  • docs/assets/screenshots/verbose-progress.jpg is excluded by !**/*.jpg
  • docs/assets/screenshots/voice-transcription.jpg is excluded by !**/*.jpg
  • uv.lock is excluded by !**/*.lock
📒 Files selected for processing (42)
  • README.md
  • docs/assets/screenshots/CAPTURES.md
  • docs/how-to/browse-files.md
  • docs/how-to/chat-sessions.md
  • docs/how-to/cost-budgets.md
  • docs/how-to/dev-setup.md
  • docs/how-to/file-transfer.md
  • docs/how-to/inline-settings.md
  • docs/how-to/interactive-approval.md
  • docs/how-to/plan-mode.md
  • docs/how-to/projects.md
  • docs/how-to/route-by-chat.md
  • docs/how-to/schedule-tasks.md
  • docs/how-to/switch-engines.md
  • docs/how-to/topics.md
  • docs/how-to/troubleshooting.md
  • docs/how-to/verbose-progress.md
  • docs/how-to/voice-notes.md
  • docs/how-to/webhooks-and-cron.md
  • docs/how-to/worktrees.md
  • docs/tutorials/conversation-modes.md
  • docs/tutorials/first-run.md
  • docs/tutorials/install.md
  • docs/tutorials/interactive-control.md
  • docs/tutorials/multi-engine.md
  • docs/tutorials/projects-and-branches.md
  • pyproject.toml
  • src/untether/markdown.py
  • src/untether/runners/claude.py
  • src/untether/telegram/commands/config.py
  • src/untether/telegram/commands/file_transfer.py
  • src/untether/telegram/commands/media.py
  • src/untether/telegram/commands/model.py
  • src/untether/telegram/commands/planmode.py
  • src/untether/telegram/commands/reasoning.py
  • src/untether/telegram/files.py
  • src/untether/telegram/loop.py
  • tests/test_config_command.py
  • tests/test_exec_render.py
  • tests/test_meta_line.py
  • tests/test_telegram_file_transfer_helpers.py
  • tests/test_telegram_files.py

📝 Walkthrough

Walkthrough

The PR adds extensive screenshot documentation across guides and tutorials, introduces a new About page in the config UI with default-value resolution logic, implements file deduplication for duplicate uploads, propagates additional fields through EngineOverrides across multiple commands, reformats footer resume lines with an emoji prefix, and adjusts related tests to reflect the new UI and formatting.

Changes

Cohort / File(s) Summary
Documentation & Screenshots
README.md, docs/assets/screenshots/CAPTURES.md, docs/how-to/*, docs/tutorials/*
Added inline screenshot images and HTML comment placeholders across 18+ documentation files to visually illustrate features, UI states, and workflows. Created new CAPTURES.md checklist for asset management. No logic changes.
Configuration UI & Engine Overrides
src/untether/telegram/commands/config.py, src/untether/telegram/commands/model.py, src/untether/telegram/commands/planmode.py, src/untether/telegram/commands/reasoning.py
Added new _page_about method and About routing ("ab"), implemented _DEFAULT_EFFECTIVE resolution mechanism to display engine-specific defaults (aq, dp, vb) on home page, propagated five additional fields (permission_mode, ask_questions, diff_preview, show_api_cost, show_subscription_usage) through EngineOverrides in set/clear paths.
File Transfer & Handling
src/untether/telegram/files.py, src/untether/telegram/commands/file_transfer.py, src/untether/telegram/commands/media.py, src/untether/telegram/loop.py
Added new deduplicate_target utility to handle duplicate file uploads by appending numeric suffixes, removed error path in _save_document_payload when file exists (now deduplicates), removed conditional caption check in _handle_media_group, changed FILE_PUT_USAGE reply to handle_file_put_default delegation for auto-put with captions.
Footer Formatting
src/untether/markdown.py
Added blank line separator and leftward-arrow emoji (↩️) prefix before resume line in MarkdownFormatter._format_footer.
Version Bump
pyproject.toml
Updated project version from 0.34.5rc2 to 0.34.5rc3.
Test Updates
tests/test_config_command.py, tests/test_exec_render.py, tests/test_meta_line.py, tests/test_telegram_file_transfer_helpers.py, tests/test_telegram_files.py
Updated home page expectations (diff-preview default label, removed versions line), added About page navigation and content validation tests, updated footer parsing tests to expect blank line and arrow-prefixed resume format, renamed file deduplication test and validated deduplicated path behavior, added deduplicate_target unit tests for various conflict scenarios.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~70 minutes

Possibly related PRs

Poem

🐰 Screenshots bloom across these docs,
An About page springs to show the clocks,
Files dedupe with numbered care,
Arrows guide where resumes fare,
Engines resolve their defaults bare!
~🐇✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 43.75% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (2 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The PR title directly references the version bump (0.34.5rc3) and accurately summarizes the two main categories of changes: docs screenshots and bug fixes. It is concise, specific, and reflects the primary intent from the developer's perspective.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
  • 📝 Generate docstrings (stacked PR)
  • 📝 Generate docstrings (commit on current branch)
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Post copyable unit tests in a comment
  • Commit unit tests in branch feature/github-hardening
📝 Coding Plan
  • Generate coding plan for human review comments

Comment @coderabbitai help to get the list of available commands and usage tips.

…vements)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@nathanschram Nathan Schram (nathanschram) merged commit 8c96a03 into master Mar 14, 2026
18 of 19 checks passed
@nathanschram Nathan Schram (nathanschram) deleted the feature/github-hardening branch March 14, 2026 05:54
Nathan Schram (nathanschram) added a commit that referenced this pull request Mar 16, 2026
Merged origin/master (rc3 docs/screenshots PR #130) into
feature/github-hardening. Kept HEAD (rc4) for all source files,
tests, and version. Regenerated uv.lock.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@coderabbitai coderabbitai bot mentioned this pull request Apr 15, 2026
11 tasks
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