Subshell Docs

Write documentation

Author and verify public documentation in the Subshell repository.

Content contract

Pages live under apps/docs/content/docs as MDX. Every page needs nonempty title and description frontmatter and an entry in its folder's meta.json.

---
title: "Install the server"
description: "Install and initialize the Subshell server on a supported host."
---

Use a factual one-sentence opener as the visible lead subtitle. Keep the metadata description for search and social previews, without displaying a second subtitle. How-to pages continue with prerequisites, numbered actions, expected results, and next steps. Reference pages use lookup tables and command sections.

Write naturally

Write as if you're explaining something to a peer. Use active voice, familiar words, and contractions like "don't" and "it's" where they sound natural. Connect related ideas and vary sentence length so the prose flows. Avoid textbook introductions, stock AI phrases, and conclusions that repeat what you've already said.

For example, "Run the transfer again to retry" reads more naturally than "re-running it is the retry." Read your draft aloud to catch stiff wording or repetitive sentence patterns. Keep technical terms, conditions, and warnings precise as you revise.

Use the same voice in app messages, website copy, and code comments. App messages should explain what's happening and offer a useful next step when one exists. Comments should explain the reason or constraint another developer needs to understand.

Keep UI titles short and fixed. Use "Close this subshell?" and identify the subshell in the body; long names, addresses, and versions shouldn't expand a heading. Buttons should name the action they perform, such as "Insert prompt" or "Revoke key".

Explain consequences and timing accurately. Generating a setup key doesn't replace a node's credentials until someone uses it. Maintenance tries to stop subshells, but some may keep running. Aim for one or two short sentences, and use more when a warning or condition needs it.

Use "subshell" for UI objects and actions, and explain it as a terminal session running an agent or a shell. Keep wording consistent across menus, dialogs, accessible labels, and guides. The product-copy examples in apps/docs/STYLE.md cover confirmations, notifications, and destructive actions.

Verify facts

Read the owning app documentation and implementation. Confirm flags, defaults, platform support, UI labels, and permissions. Use docs/security.md as the security authority and preserve warnings about trust or destructive operations.

Keep server, node, and client meanings distinct. Follow apps/docs/STYLE.md for plain second-person prose, precise UI labels, installation priorities, and review checks. Recommend the desktop apps first, CLI setup second, and direct installation downloads to subshell.sh.

MDX and navigation

Use standard code blocks, tables, and GitHub alerts. Put placeholders such as <path> and JSON braces inside code spans or blocks. Internal links must start at the site root and point to a real page. Don't add draft placeholders or unrelated custom MDX components.

For diagrams, use fenced mermaid blocks and start each with a %% description for its accessible label. The build converts diagrams to themed SVGs that work without JavaScript. Explain the diagram in prose and check the exported image.

Add screenshots when they help readers find controls or understand a layout. Use Fumadocs ImageZoom with unoptimized inside a native figure so readers can open a larger view. Follow the style guide for cropping, alt text, captions, redaction, and the 320px display-height limit. Keep the full instructions in the text too.

When describing a UI action, name the interface, navigation path, control label, and required permissions. Readers shouldn't have to guess where a card or dialog lives.

Navigation and AI section order are shared in apps/docs/lib/navigation.ts. Every section has an index page. The content tests enforce the tree.

Implementation examples

Developer tutorials should include the files and commands needed to build and test the example. Pin package and manifest contract versions separately, exercise failure cases, and inspect the packed artifact. When a compiled host loads external code, test that case without neighboring workspace dependencies. Clearly label fictional CLI fixtures and the vendor testing still needed before claiming real integration support.

Keep Presets and Reusable Prompts distinct. Explain library references versus copied launch text, instance-wide sharing, and typing versus submitting a prompt. Use screenshots of meaningful agent tasks and settings rather than isolated generic fields.

Verify the site

env -u SHELLOPTS -u BASHOPTS bun run --cwd apps/docs test
bunx turbo build --filter=@internal/docs
bun run --cwd apps/docs lint:check
bun run --cwd apps/docs verify-types
bun run --cwd apps/docs verify:export

The build compiles MDX and generates HTML, search, sitemap, and AI text exports. Export verification checks page coverage, metadata, and complete readable content.

Ship the change

Add a changeset for @internal/docs only. Update existing repository links when routes change, and preserve historical engineering specs as dated records.

Next steps

Preview with bun run dev:docs on port 3400 and review wide and narrow layouts. Read the prose as well as running checks; passing tests doesn't establish factual accuracy.

Edit on GitHub

Last updated on

On this page