The manual already covers several advanced Context and RequestContext methods, but the material is spread across multiple pages. docs/manual/context.md introduces the type and some core helpers, while routeActivity() is documented in docs/manual/inbox.md, signed-request helpers such as getSignedKeyOwner() appear in docs/manual/access-control.md, and remote lookup methods are split across docs/manual/webfinger.md and docs/manual/nodeinfo.md.
That makes the higher-level Context API harder to discover than it should be. If a reader wants to understand what Context can do beyond URI building and basic dispatch, they currently need to jump across several sections of the manual.
I think we should add a dedicated guide for advanced Context usage, tentatively in docs/manual/context-advanced.md, and link to it prominently from docs/manual/context.md. The goal would not be to duplicate every existing section, but to gather the advanced methods in one place, explain when to use them, and link back to the more detailed protocol-specific pages where needed.
Proposed scope:
parseUri()
routeActivity()
getSignedKey() and getSignedKeyOwner()
getDocumentLoader() and authenticated document loading patterns
getActorKeyPairs()
- remote lookup helpers such as
lookupObject(), lookupWebFinger(), lookupNodeInfo(), and traverseCollection()
RequestContext.request and RequestContext.url, if we want the page to serve as a complete guide to request-aware context helpers
Expected outcome:
- add a dedicated advanced
Context guide in docs/manual/
- add clear cross-links from docs/manual/context.md
- reduce the need to discover these methods indirectly through unrelated pages
- keep protocol-specific caveats in their existing pages, but add concise summaries and links from the new guide
- include examples that explain when to use each helper, not just what it returns
A few topics need especially careful treatment:
- security and trust semantics of
routeActivity()
- authorized fetch and instance-actor patterns around
getSignedKey() and getSignedKeyOwner()
- when to use
lookupObject() directly versus lookupWebFinger()
- when
getDocumentLoader() is necessary instead of the default loader
The manual already covers several advanced
ContextandRequestContextmethods, but the material is spread across multiple pages. docs/manual/context.md introduces the type and some core helpers, whilerouteActivity()is documented in docs/manual/inbox.md, signed-request helpers such asgetSignedKeyOwner()appear in docs/manual/access-control.md, and remote lookup methods are split across docs/manual/webfinger.md and docs/manual/nodeinfo.md.That makes the higher-level
ContextAPI harder to discover than it should be. If a reader wants to understand whatContextcan do beyond URI building and basic dispatch, they currently need to jump across several sections of the manual.I think we should add a dedicated guide for advanced
Contextusage, tentatively in docs/manual/context-advanced.md, and link to it prominently from docs/manual/context.md. The goal would not be to duplicate every existing section, but to gather the advanced methods in one place, explain when to use them, and link back to the more detailed protocol-specific pages where needed.Proposed scope:
parseUri()routeActivity()getSignedKey()andgetSignedKeyOwner()getDocumentLoader()and authenticated document loading patternsgetActorKeyPairs()lookupObject(),lookupWebFinger(),lookupNodeInfo(), andtraverseCollection()RequestContext.requestandRequestContext.url, if we want the page to serve as a complete guide to request-aware context helpersExpected outcome:
Contextguide in docs/manual/A few topics need especially careful treatment:
routeActivity()getSignedKey()andgetSignedKeyOwner()lookupObject()directly versuslookupWebFinger()getDocumentLoader()is necessary instead of the default loader