docs(khal-os): SDK hooks + services — 6 pages#4
Merged
Conversation
Authored 6 MDX pages for the FDE-facing SDK surface: sdk/ - hooks-reference.mdx (index page linking the three hooks) - useNats.mdx (pub/sub/request over the platform NATS bridge) - useKhalAuth.mdx (current user + org + role) - useService.mdx (transport-agnostic client for your own backend) services/ - backend-overview.mdx (what a pack service is, shape, lifecycle) - environment-config.mdx (khal-app.json env[] declaration + runtime injection) All hook signatures verified against app-kit/packages/os-sdk/src/app/hooks.ts. Examples cite pack-terminal (full-stack reference) and pack-settings (frontend-only useKhalAuth). docs.json navigation updated with SDK and Services groups under the existing guides tab. Kernel guardrails respected: no core/platform/brain/deploy source citations; contracts-over-mechanisms; NATS surface only (no cluster, JetStream, or khal.catalog.* internals); JWT/WorkOS explicitly out-of-scope. Wish: .genie/wishes/docs-khal-sdk/WISH.md
This was referenced Apr 17, 2026
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
2 participants
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
Adds 6 MDX pages for the FDE-facing SDK surface, plus navigation wiring in
docs.json.SDK hooks —
sdk/hooks-reference.mdx— landing + index table linking each hookuseNats.mdx— pub / sub / request-reply over the platform NATS bridge, with subject-naming guidance and the required<Warning>against subscribing tokhal.internal.*/khal.catalog.*useKhalAuth.mdx— current user, org, role, andsignOut; explicit about what is not exposed (JWT, session, refresh) per kernel guardrailsuseService.mdx— transport-agnostic client (appId) for your own pack backend, with request / publish / subscribe / portsPack services —
services/backend-overview.mdx— what a pack service is, directory shape, lifecycle (platform-managed), transport (NATS-first)environment-config.mdx—khal-app.jsonenv[]declaration,type: 'secret'vs'string', runtime injection, frontend-never-reads-secretsSource-of-truth verification
All hook signatures were read from
app-kit/packages/os-sdk/src/app/hooks.tsbefore writing. Examples citepack-terminal(full-stack reference) andpack-settings(frontend-only).Kernel guardrails
Test plan
Wish: `.genie/wishes/docs-khal-sdk/WISH.md`