docs: b.yaml toolchain page, service-vs-target note, drop the private-repo pointer - #162
Merged
Conversation
…-repo pointer Three pieces of public-docs debt: - New guide page "The Toolchain (.bin/b.yaml)": what b is, the b.yaml fields lok8s actually uses (alias, asset, file, onPost, version, and the groups tag convention), the five env-sync profiles with their select filtering, and how b install / b update fit the lo workflow. Registered in the VitePress sidebar and cross-linked from Getting Started. - services.md: admonition that service names (services.yaml keys, image + lok8s.dev/name label) and target names (clusters/<domain>/targets/ directories) are distinct namespaces, and which commands take which. - config.ts: the srcExclude comment no longer points readers at a private repo; it now states the defensive intent only. Verified against the real .bin/b.yaml and the b source/docs (github.com/fentas/b); vitepress build docs passes. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016DJzGS3pNBzZs1jaEQ74Co
There was a problem hiding this comment.
Pull request overview
This PR updates the public documentation site to reduce “public-docs debt” by adding a dedicated Toolchain guide for .bin/b.yaml, clarifying the distinction between service names and target names, and removing a lingering pointer to private/internal material in the VitePress config comments.
Changes:
- Add a new guide page documenting how
band.bin/b.yamlwork in a lok8s project, and link it from the sidebar and Getting Started. - Add a warning callout in the Services guide explaining service-name vs target-name namespaces and label-based selection.
- Update the VitePress config comment to remove mention of a private repo while keeping
srcExcludeas a safety net.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| docs/guide/toolchain.md | New Toolchain guide page explaining b, .bin/b.yaml, and profile filtering behavior. |
| docs/guide/services.md | Adds a warning admonition clarifying service-name vs target-name behavior and lo deploy -l label selection. |
| docs/guide/index.md | Cross-links Getting Started text to the new Toolchain page. |
| docs/.vitepress/config.ts | Removes private-repo mention from a comment and adds the new Toolchain page to the Guide sidebar. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+38
to
+39
| except the labels you put on the target's manifests. `lo deploy -l | ||
| lok8s.dev/name=<x>` selects by **label value**, not by target directory. |
Comment on lines
+43
to
+45
| so teammates and CI get the identical toolchain. The | ||
| `curl -fsSL https://get.lok8s.io | sh` bootstrap from | ||
| [Getting Started](/guide/#installation) runs these same commands for you. |
|
|
||
| | Profile | Includes | Adds | | ||
| |---|---|---| | ||
| | `core` | — | `.lok8s/**`, `.envrc`, skills, and the `core`-tagged binaries | |
…b version, complete the profile rows The review checked the page against b's own source and caught a wrong claim: PATH_BIN/PATH_BASE are returned verbatim by GetBinaryPath, and only the git-root and cwd fallbacks append .bin. A public schema doc that is wrong is worse than no doc. Added the version anchor for the silent-failure mode: b ignores unknown keys, so a field name from another version installs the binary with default behavior and reports nothing. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016DJzGS3pNBzZs1jaEQ74Co
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
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.
Night-queue C-10: public-docs debt.
1. Pointers to private material
The queue item assumed ~5 dead pointers to private docs. A full sweep found one:
docs/.vitepress/config.ts(srcExclude comment)Sweep evidence (all clean, no changes needed):
docs/internal,kubehz-cluster, or privatekernpilot/*repo references in any.mdunderdocs/,README.md, or the top-level markdown files.github.com/kernpilot/lok8s/tree|bloblinks resolve to paths that exist in the repo; the only other org repo linked (kubehz-agent) is public.2. New guide page: The Toolchain (
.bin/b.yaml)docs/guide/toolchain.md, registered in the sidebar (Introduction, after Concepts) and cross-linked from Getting Started. Covers:bis (github.com/fentas/b) and what it owns in a lok8s project (binaries + framework file sync),binariesfields lok8s actually uses —version,alias,asset,file,onPost(with theB_*hook env vars), and thegroupstag with an explicit note that it is a lok8s convention, not abfield,selectships a filteredb.yamlper profile,b install/b update/b version --check/b verifyfit theloworkflow.Every field was verified against the live
.bin/b.yamland thebsource/docs (pkg/binary/types.go,docs/env-sync.mdx). Nothing undocumented-in-b was invented.3. Service name vs target name
docs/guide/services.mdgains a warning admonition right after the what/how paragraph: service names (services.yamlkeys → imagelok8s.local/<service>+lok8s.dev/namelabel, used by Tilt) and target names (clusters/<domain>/targets/directories, used by the domain kustomization andlo build) are distinct namespaces;lo deploy -lselects by label value, not by target directory.Verification
vitepress build docspasses in the branch (dead-link check included).#plane-b-—-workloads-targetsanchor was verified against the rendered HTML (VitePress keeps the em dash in the slug).🤖 Generated with Claude Code
https://claude.ai/code/session_016DJzGS3pNBzZs1jaEQ74Co