Ghost Protocol — Documentation Editorial Guide

Public docs follow GitHub Docs best practices and a mandatory security cleanse before every page ships.

Content types

Type	Use when	Line budget (public subset)
Quickstart	First success in under 30 minutes	80–120
How-to	One task start-to-finish	60–150
Concept	Mental model before tasks	40–100
Reference	Lookup contracts and APIs	Split if over 200
Troubleshooting	Fix a specific failure	Symptom → Cause → Fix per issue

Article template

---
title: Human-readable title
---

## About this article
- **Audience:** …
- **Goal:** After reading, you can …
- **Type:** Quickstart | How-to | …

## Summary
One paragraph: conclusion first (what you will accomplish).

## Prerequisites
- Bulleted, linkable

## … body …

## Next steps
- Link 1
- Link 2

## Operator depth
Live fleet state and harness evidence live in private operator handoff (not published) (private).

Voice

• Active voice, plain language, one idea per sentence
• Link jargon to glossary on first use
• Do not repeat the public-safe disclaimer in the body (sync prepends it once)
• Bold sparingly (under 10% of text)
• Inverted pyramid: most important information first in each section

Security cleanse checklist (required before editorialStatus: done)

• [ ] No passwords, API keys, or sk_ / AIza tokens
• [ ] No [pi-password-placeholder], TronShadow####, or real credential strings
• [ ] No private IPs (192.168.*) or macOS home paths (/Users/…)
• [ ] No /tmp/ artifact paths in prose
• [ ] No personal names (staff, founders, operators) — use "Ghost Protocol team"
• [ ] No site-specific physical labels ("Front Door", "Cabin Rear") — use site-role-a / site-role-b
• [ ] No live container UUIDs, fingerprints, soak percentages, or session/subagent IDs
• [ ] No file:line implementation references in public pages
• [ ] Commands use PHANTOM_PROXY, YOUR_DEVICE_PASSWORD, <device-ip> placeholders
• [ ] No COGS, margins, Stripe secrets, or internal cost data
• [ ] Handoff referenced once at bottom — no verbatim dumps or blockquotes

Forbidden in public subset

These sources are internal-only — do not sync to ghostprotocol.us/docs:

• HANDOFF_QUEUE.md, full GRADING_CRITERIA.md, appendices/living-sources.md
• appendices/internal-plans/**

Placeholder conventions

Instead of	Use
Real Pi password	YOUR_DEVICE_PASSWORD
Device IP	<device-ip> or role label
Proxy host	https://<phantom-proxy>:8788
Workspace path	[repo-root]
Artifacts	[operator-artifacts]

Review gates

1. node scripts/audit-docs-secrets.mjs (gp-site-v2) — source scan
2. npm run vet:docs (gp-site-v2) — sync + audit
3. bash build.sh (oak-vms-firmware/docs) — VitePress build