docs: rework the README top section and refresh the demo transcripts - #60
Merged
Conversation
Closes #42, #43, #44, #45, and most of #46. The first code block called an undefined smtp.send() and never invoked the tool, so the first thing a reader pasted raised NameError. The runnable example was the *second* block, and pip install sat ~190 lines further down. Quickstart now leads with install, then a single block that runs as-is and prints exactly what the README claims -- and it showcases URLAllowList rather than the three-keyword default, so the lead example is the rule that actually holds up. The duplicate Try It Now section is gone. demo.py used a different payload in each half, with a comment saying "for variety". Part 1's body contained API_KEY, which the default filter would have blocked too, so the "unguarded breach" was only a breach because the guard was absent -- and a skeptic reads a swapped payload as staged. Both halves now use one identical payload, making @shield_tool the only variable, and the README transcript is the real output rather than a hand-edited one. The scanner transcripts predated the 0.3.6 attacker-call rewrite: they showed "Evolving a more deceptive variant", a line the current code never prints. Both are replaced with one real run that also demonstrates the adaptive claim, which nothing in the README previously did -- a seed is refused, mutated, and breaks through at generation 2 (4 attempts across 3 seeds). Softened "falls to its third mutation" to match what is actually shown, and dropped the unfamiliar glm-5.2:cloud example in favour of prose about the aligned-target path. Also adds async and error-handling examples, states the fail-open consequence for uninspected types instead of only listing them, notes the package is pre-1.0, and moves Roadmap out from between Limitations and the scanner.
higagan
force-pushed
the
docs/readme-ux-fixes
branch
from
August 4, 2026 15:44
ef16299 to
206bacb
Compare
This was referenced Aug 4, 2026
Closed
Closed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #42, #43, #44, #45, and most of #46. Leaves #41 alone — it's labelled
good first issue.#42 — the first code block called an undefined
smtp.send()and never invoked the tool, so the first thing a reader pasted raisedNameError; the runnable one was the second block, andpip installsat ~190 lines below. Quickstart now leads with install, then one block that runs as-is. Duplicate section removed.#44 — that lead block now showcases
URLAllowListrather than the keyword default, so the first thing a reader sees is the rule that actually holds up.#43 —
demo.pyused a different payload in each half ("for variety"). Part 1's body containedAPI_KEY, which the default filter would have blocked too, so the swap read as staged. Both halves now use one identical payload;@shield_toolis the only variable.#45 — bigger than the issue said: the transcripts predated the 0.3.6 rewrite and showed
Evolving a more deceptive variant, a line the current code never prints. Replaced with a real run that also demonstrates the adaptive claim for the first time — a seed refused, mutated, breaking through at generation 2 (4 attack attempts across 3 seeds). Softened "third mutation" to match, droppedglm-5.2:cloud.#46 — async and error-handling examples, the fail-open consequence spelled out rather than just listing inspected types, a pre-1.0 note, and Roadmap moved out from between Limitations and the scanner.
Verified: the Quickstart block's output is byte-identical to what it prints, the demo transcript is byte-identical to
python demo.py, the scanner transcript is a real captured run, no stale strings remain, 97 tests and ruff pass.