docs: restructure README (glossary, dropdowns), add ROADMAP, rewrite FAQ - #27
Merged
Conversation
- State plainly that an Envelope records a boundary's I/O (input and return value) and does NOT capture side effects that run inside it (file writes, network calls, DB writes, time). This is called out in both Architecture and Quick start, since it is the reason replay is deterministic and safe. - Rework Quick start into three numbered steps (wrap client, mark your own @boundary, record a fixture) and add a "which entry point" table. - Consolidate the scattered recording helpers (wrap, wrap_llm, instrument_langgraph, EnvelopeRecorder) into one "Recording entry points" section, replacing the old buried wrap_llm text (which had a broken sentence) and the separate LangGraph section. - Update nav; put the PyPI install line first. Supersedes #26. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Signed-off-by: Tisha Chawla <tisha.chawla2020@vitalum.ac.in>
The old FAQ was thin and marketing-shaped. Replace it with grouped, substantive answers covering the practical gaps: what counts as a boundary and how many to add; how to write a replay test; whether replay runs tools / side-effecting code (stubbed no, cut-point live yes); how calls are matched on replay (name + invocation index, so loops/retries work); what happens when the code path diverges from the fixture (clear KeyError); recording overhead; which providers wrap() supports; streaming; Python versions; and production readiness. All answers verified against the code (session matching, captured_result / call_log, KeyError on missing envelope, wrap() provider detection). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Signed-off-by: Tisha Chawla <tisha.chawla2020@vitalum.ac.in>
tishachawla-jg
changed the title
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.
Docs-only. Makes the README skimmable and defines the jargon in one place.
Structure
on_crossing, env vars,EnvelopeRecorder, project structure) moved under an Advanced section of dropdowns. Each recording helper and each verification layer is its own dropdown.stub/liveare made explicit at the cut-point example.Content
Cut
No em/en dashes. Supersedes #26 (closed).