msb-docs
The documentation site and the README's pictures: how a page is written (the four page kinds by section, the voice, the table shapes for commands, config keys and troubleshooting), docs/content Markdo
SKILL.md.agents/skills/msb-docs/SKILL.md
GitHubDocs
Detail carved out of AGENTS.md, which keeps only what has to hold in
every session. Repo-specific throughout; the facts here are verified against
msb 0.7.6 and re-checked on 0.7.7.
docs/— the documentation site (GitHub Pages,.github/workflows/docs.yml). Pages are Markdown indocs/content/withtitle/section/orderfront matter;docs/build.pyis a stdlib-only converter for a deliberate Markdown subset (extend it rather than adding a generator), plustemplate.htmlandassets/(terminal theme, light/dark/auto, client-side search over an index it writes as a script so the site works offfile://).CHANGELOG.mdis rendered as a page, never copied; the logo comes from the repo-levelassets/. The same build writes the SEO/agent outputs (canonical, Open Graph, JSON-LD,sitemap.xml,llms.txt,llms-full.txt, a.mdcopy of each page), all derived from the pages and--site-url, so a new page needs only its front matter — including thedescription, which--checkrequires.--check(run bycheck.sh) fails on a broken internal link or anchor and on anymsbctlsubcommand without a### \msbctl <name>`` section on the Commands page. A user-visible change updates the relevant page in the same PR, like its changelog line.assets/— the logo:msb-manager-mark-dotmatrix-dark.svg(for dark grounds, also readable on light; the README's header) andmsb-manager-icon.svg.scripts/screenshots/—make.shregeneratesdocs/assets/screenshots/*.svg(used by the README): the realmsbctl/msb-pickerin a fixed-size tmux against an invented HOME (world.py), a fakebin/msband abin/msbctlwrapper that skips only the/dev/kvmpreflight;render.pyturns the captured grid into an SVG terminal (fixed cells, box lines drawn as strokes, docs palette). Needs tmux and fzf. Re-run it when a screen it shows changes; never hand-edit the SVGs or put real names, hosts or tokens inworld.py.
Writing the pages
The site borrows its shape from Diátaxis and keeps its own voice. A page is one kind, set by its section, and doesn't drift into another; when it starts to, split it and link.
| Section | Kind | A page here |
|---|---|---|
| Start here | tutorial | one path, in order, from nothing to a working sandbox; no options the reader doesn't need yet |
| Guides | how-to | one task, named for the task ("Folders & ports", not "Advanced"). Opens with a sentence on when you need it. Commands first, then the why of each step |
| Concepts | explanation | why it works this way, and what it does not protect. No steps |
| Reference | reference | complete and terse: every command, flag, key, type and default, in tables. Behaviour in a sentence; the why is linked, not repeated |
Voice, which is what the docs are for:
- Say why, and say what fails. "It's deliberately not
set -e", "It's a missing egress rule until proven otherwise." A failure the page predicts saves a debugging session. Never trade this away for brevity. - Second person, plain verbs, short paragraphs. One condition per sentence. When a paragraph needs three "unless"es, it wants a list or a table.
- No dating. Behaviour is stated as it is, never as a change ("now", "no longer", "used to", "current msb-manager"); that's the changelog's job. An upgrade step names its condition instead: "a sandbox created before the filtered agent existed needs one rebuild".
- Define before relying. A term with a specific meaning (placeholder, policy pin, registry entry, rule group, feature) is defined where it's first used or is in
glossary.md; add the row when you add the term. - No filler and no marketing. No "In this section we will", no "simply", no adjectives doing a claim's job. Say what's not covered as plainly as what is.
- Specific over general. Exact paths, values, defaults, limits and error strings; a reader searching for an error message should land on the heading that quotes it.
Shapes that repeat:
- Commands (
commands.md):### \msbctl <name>`, atextsynopsis, behaviour in prose, then an| Option | Meaning |table (and| Action | Does |for verbs with sub-actions). Options come from the argparse parser; check them againstmsbctl <name> --help`, never from memory. - Configuration (
configuration.md):| Key | Type | Default | Meaning |, with types from the "Value types" table; validation the code enforces goes in that table or the row, never guessed. - Troubleshooting: the heading is the symptom as the user sees it, the error string where there is one. Then the cause in one bold sentence, then the fix as commands.
- Callouts:
> **Note:**,> **Tip:**,> **Warning:**only; a warning is for what loses data or opens the network.