docs: tech editor pass + delegation accuracy fix#13
Merged
devonartis merged 6 commits intodevelopfrom Apr 15, 2026
Merged
Conversation
added 6 commits
April 14, 2026 20:22
Sets reader expectations before the first code block and aligns both docs against the actual SDK API. README.md - Add Prerequisites section (broker + credentials + env vars) - Add inline TOC for scannability - Quick Start opens with pointer to Prerequisites - Fix agent.release missing parens (silent no-op) - Tighten orphan sentence, break run-on demo description - Troubleshooting blockquote with actual exception classes docs/getting-started.md - Expand Prerequisites with two-path framing - Qualify "5 minutes" claim - Fix orchestration order (challenge before keygen) - Use agent.bearer_header convenience accessor - Add Testing Guide and MedAssist Demo to Next Steps Refs devonartis/agentwrit#31 Generated with Claude Code
Aligns the dev guide with the README and getting-started polish, promotes a real SDK limitation from a buried sub-clause to a proper callout, and tightens informal headings. - Frontmatter cross-links to README Prerequisites - Basic Pattern uses agent.bearer_header accessor - Long-Running Tasks: hedge note on broker lifetime cap - Single-Hop Delegation: document delegate(ttl=N) keyword - Multi-Hop: promote registration-token constraint to blockquote - Rename "What We Learned About Delegation" → "Delegation Behavior" - Rename "Garbage Tokens" → "Invalid Tokens" - Fix result.claims.iss comment — broker-configured, not fixed - Next Steps: add Testing Guide and MedAssist Demo rows Refs devonartis/agentwrit#31 Generated with Claude Code
Alignment, navigation, and grounded error-code enumeration. - Add inline TOC (6 anchors) - Frontmatter pointer to Getting Started and Developer Guide - close(): note AgentWritApp is not a context manager, show try/finally pattern (verified: no __enter__/__exit__) - jti: soften from "32 hex chars" to "broker-assigned" - ProblemDetail: enumerate all 10 known error_code values - Call out the 403 trap: scope_violation and insufficient_scope both surface as AuthorizationError - AuthorizationError: expand to 3 sub-cases with error_codes Refs devonartis/agentwrit#31 Generated with Claude Code
Voice consistency and framing updates to match the new README/getting-started structure. - Frontmatter pointer to Getting Started for code-first readers - Operator role: acknowledge solo-broker path (both hats) - "Common Scope Mistakes" → neutral voice - Delegation rules: verified-against-broker intro - Multi-hop: blockquote callout matching developer-guide - validate() generic error scoped to validate endpoint only - Fix bare broker_url → app.broker_url (2 occurrences) - Next Steps: add Testing Guide and MedAssist Demo Refs devonartis/agentwrit#31 Generated with Claude Code
- Frontmatter links to README Prerequisites - Fix stale credentials advice: register your own app, don't rely on hardcoded values in run script (TE-6, TE-13) - pytest is now primary path, wrapper script secondary - Inline caveat on test_acceptance_1_8.py filename (all 15 stories, rename is a follow-up) - Rate limit manual recovery note - Next Steps table for doc parity Refs devonartis/agentwrit#31 Generated with Claude Code
The broker's ScopeIsSubset is a non-strict subset check — equal
scope passes, any scope the delegator doesn't hold is rejected.
Same-scope delegation is accepted and verified in acceptance
Story 8 ("Delegate All Scope — No Narrowing").
Canonical phrasing: "Delegation cannot widen authority. Equal or
narrower scope is accepted."
Files: README, concepts, developer-guide, sample-apps (04, 05,
README), sample-app-mini-max, demo guides, operator template,
scope.py docstring, models.py docstring, integration test banner,
sdk-core s7_delegation.py.
Broker-side fix filed as devonartis/agentwrit#41.
Refs devonartis/agentwrit#31
Generated with Claude Code
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.
Summary
Full tech editor pass on all core docs + delegation accuracy fix across 14 files.
Tech editor pass (6 commits):
Delegation accuracy fix (1 commit):
Test plan
uv run ruff check .— passeduv run mypy --strict src/— passed (source code changed in scope.py, models.py)uv run pytest tests/unit/ -q— 99 passedagentauthstrings in changed filesRefs devonartis/agentwrit#31
Generated with Claude Code