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.

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 default code blocks, tables, and GitHub alerts. Keep placeholders such as <path> and JSON braces inside code. Internal links are root-relative and must resolve to a real page. Do not add draft placeholders or unrelated custom MDX components. Use fenced mermaid blocks for diagrams; start each with a %% description for its accessible label. Diagrams render to themed SVG during the build and remain visible without JavaScript. Keep an explanation in prose and verify the exported SVG. For screenshots, use the built-in Fumadocs ImageZoom component with unoptimized inside a native figure; selecting it opens a larger image overlay. Use screenshots only where they clarify controls or layouts. Follow the style guide for cropped figures, alt text, captions, redaction, and the 320px display-height limit. Keep complete instructions in prose. For UI actions, name the interface, navigation path, and control label, and state required permissions; do not assume readers already know 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 does not establish factual accuracy.