Phantom Vision VMS / Ghost Protocol

Appearance

About this article ​

  • Audience: Contributors shipping firmware releases and keeping the public docs hub accurate
  • Goal: After reading, you can align verification gates with a release, run the docs security cleanse, and rebuild the VitePress site before publish
  • Type: How-to

Summary ​

A Ghost Protocol release coordinates edge firmware, Phantom orchestration, and verification harnesses. Public docs describe capabilities and procedures; detailed gate percentages and soak tables stay in private operator handoff. Every docs change must pass the security cleanse and a local VitePress build before sync to the public site.

Prerequisites ​

Release gate tiers (public summary) ​

Gates stack from encoding stability through detection authority, federation, and firmware manager drift checks.

TierFocusPublic pass themes
T1H.265 recording and soakFresh chunks at expected fps, thermal limits held, soak gate PASS
T2RF-DETR precomputed detectionsHarness scenarios meet minimum pass rate on live MCP
T3Gemma / A2A / Hermes zero-trustSigned agent queries, graceful offline notes, mesh active
T4Firmware managerNo manifest drift across health, CLI, and poll surfaces

Fleet-wide promote decisions require both canary shadows meeting policy on critical tiers. Run verification layers in Testing before claiming a tier bump. Exact thresholds, historical soak rows, and remainders live in operator handoff—not in public pages.

Pre-release verification checklist ​

  1. Soak and contract — Orchestrator batch with --prune-first --visual --tap on canary before fleet-wide promote.
  2. Readiness — Phantom modules PASS after stack up; remediate via approved playbooks if critical.
  3. Docs audit — No credentials, private IPs, personal names, or live fleet IDs in pages marked for public sync.
  4. Site vet — Run node scripts/audit-docs-secrets.mjs and npm run vet:docs in the gp-site-v2 publishing project when available.

Docs hub maintenance process ​

The VitePress hub under oak-vms-firmware/docs/ is the polished presentation layer over requirements, architecture, operator guides, and reference material.

When handoff or code changes materially:

  1. Read the relevant operator handoff section (private) for current fleet state—do not paste it verbatim into public pages.
  2. Update the targeted public page with concept summaries, placeholders, and symptom → fix troubleshooting patterns per EDITORIAL.md.
  3. Cross-link related guides (recovery, soaks, API quick reference) instead of duplicating long tables.
  4. Move historical planning notes to appendices/internal-plans/—they do not sync to the public site.
  5. Rebuild locally and fix broken links.

Article template every page should follow:

  • About this article (audience, goal, type)
  • Summary (conclusion first)
  • Prerequisites
  • Task body
  • Next steps
  • Operator depth (single handoff link)

Security cleanse (required) ​

Before marking a page editorialStatus: done, confirm:

  • Placeholders only: YOUR_DEVICE_PASSWORD, <device-ip>, PHANTOM_PROXY, [repo-root], [operator-artifacts]
  • No private IPs, macOS home paths, temporary artifact paths, or staff names
  • No live container UUIDs, soak percentages, session IDs, or file:line implementation citations
  • No COGS, margins, or payment secrets
  • No repeated public-safe disclaimer in the body (sync prepends it once)

Build and publish the docs site ​

bash
cd [repo-root]/oak-vms-firmware/docs
nvm use 22
npm ci
bash build.sh

The build wrapper rejects Node versions outside 20–22. CI should pin Node 22. Static output from .vitepress/dist/ deploys behind a /docs/ base path using the same patterns as other frontend deploy scripts in cost-sentinel.

Local preview while editing:

bash
npm run docs:dev

Historical content reorg ​

Heavy planning documents (phase notes, bulk reviews, implementation kanban exports) belong under appendices/internal-plans/. Keep user-facing sections clean: quickstart, operator guides, architecture, reference, troubleshooting, contributing. Update index.md navigation when adding new top-level pages—do not delete historical files; move or archive with pointers in the internal-plans README.

AI-assisted doc updates (optional) ​

For large rewrites, use a plan-then-act agent workflow: explore handoff and code with read-only tools, draft against EDITORIAL.md, then apply edits with unique anchors. Parallel exploration helps API catalogs and cross-link passes. Preserve handoff .bak files in the private repo; public pages never include .bak content or blockquotes from handoff.

Next steps ​

Operator depth ​

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