docs(khal-os): FDE manual v1 — VC-ready (20 pages + branded nav)#8
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
- Rewrite docs.json with Khal OS brand + 20-page FDE manual IA - Author index.mdx (Home) with cross-org narrative + Day-1 card - Author what-is-khal-os.mdx (FDE framing, kernel black-boxed) - Delete Mintlify Starter Kit boilerplate: ai-tools/*, api-reference/*, essentials/*, development.mdx, quickstart.mdx Kernel-protection guardrails applied throughout. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- getting-started/clone-workspace.mdx - getting-started/install-dependencies.mdx - getting-started/your-first-pack.mdx - packs/anatomy-of-a-pack.mdx - packs/khal-app-json.mdx Sources: khal-os/genie README, app-kit/packages/types manifest, pack-template README + khal-app.json. Kernel-protection guardrails applied. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- patterns/frontend-only-pack.mdx — pack-settings canonical pattern - patterns/full-stack-pack.mdx — pack-terminal PTY+NATS canonical pattern - dev/local-dev-and-testing.mdx — unified build/test/debug loop - release/publish-your-pack.mdx — CI-driven npm + Docker + Helm flow - release/customer-install.mdx — thin handoff contract for customer admins - reference/khal-app-json-schema.mdx — manifest field reference (derived from @khal-os/types) - reference/example-packs.mdx — matrix of reference pack repos Kernel-protection guardrails applied throughout: no core/platform/brain/deploy internals, contracts exposed over mechanisms, NATS surface only. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…n frontend-only-pack
Review flagged (report at genie-docs/reports/pr-review-2026-04-17.md):
- useKhalConfig() does not exist in app-kit/packages/os-sdk — removed.
- useKhalAuth() returns {userId, orgId, role, permissions, loading}, not {user, signOut}.
- Realigned code example with actual KhalAuth interface from app-kit/packages/types/src/auth.ts.
- Noted explicitly that sign-out is a shell concern, matching sdk/useKhalAuth.mdx.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
docs(khal-os): home, narrative, IA rewrite — VC v1
docs(khal-os): SDK hooks + services — 6 pages
docs(khal-os): getting started + pack fundamentals — 5 pages
docs(khal-os): patterns + dev + release + reference — 7 pages
Lists every <Frame> placeholder in the docs site with capture setup, shot, and caption brief. Operator can systematically walk through and capture every needed screenshot without hunting through .mdx files. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Polish pass per khal-os-polish-findings.md. Seven pages were missing the 'What's next' navigation pattern established in your-first-pack and full-stack-pack: - getting-started/clone-workspace → install-dependencies + your-first-pack - sdk/useNats → useKhalAuth + useService - sdk/useKhalAuth → useNats + useService - sdk/useService → backend-overview + full-stack-pack - services/backend-overview → environment-config + publish-your-pack - services/environment-config → backend-overview + customer-install - reference/khal-app-json-schema → example-packs + anatomy-of-a-pack Zero new pages, zero scope expansion — just makes the existing 20-page manual navigable without rely on nav alone. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
docs(khal-os): screenshot capture manifest for nmstx.khal.ai
docs(khal-os): FDE manual polish pass — add cross-links to 7 pages
…ignore Mintlify broken-links was flagging 10 missing image paths referenced by <Frame> placeholders in the FDE manual. Added 1x1 transparent PNG stubs at each path so the site renders with zero broken-link warnings. Real captures will overwrite these in place per images/MANIFEST.md. Also adds .gitignore (repo had none) to keep node_modules / .mintlify out of the tree. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
docs(khal-os): image placeholders + .gitignore — zero broken links
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
First release of the Khal-OS Forward Deployed Engineer Manual — 20 pages covering the full FDE journey from
clone-workspacetocustomer-install. Replaces the unmodified Mintlify Starter Kit.Reviewed by Claude + council verdict at
genie-docs/reports/khal-os-council-verdict.md. Every page carries the 5 kernel-protection guardrails (nocore/platform/brain/deployinternals leaked).Merged into this release
Content map
Cross-org narrative (on the Home page)
Kernel-protection guardrails (applied + review-verified)
core/,platform/,brain/,deploy/source citations.useKhalAuth— documents{userId, orgId, role, permissions, loading}, not JWT/WorkOS internals).khal-app.json; platform injects.release/customer-installintentionally thin.<Warning>againstkhal.internal.*/khal.catalog.*subscriptions.Review trail
Full PR-by-PR review with signature verification at
genie-docs/reports/pr-review-2026-04-17.md. One blocking issue was fixed inline (PR #7'spatterns/frontend-only-pack.mdxreferenced a fabricateduseKhalConfig()hook and the wronguseKhalAuthshape; both corrected againstapp-kit/packages/types/src/auth.tsbefore merge).Outstanding (non-blocking)
<Frame>with descriptive alt text, no pixels yet) — to be captured fromnmstx.khal.aipost-merge.Generated by the autonomous docs-sprint orchestrator.