DocOps Workflow

Standard operating procedure for EchoHuman / Southville Forge documentation governance.

Quick Start for AI Agents

Before any work:

1. Read PROJECT-BOOTSTRAP.md — canonical source location, commands, rules
2. Read AGENTS.md — AI agent instructions for this repository
3. Identify: source path, deployment path, relevant docs, inventory files

After any infrastructure/project change:

./scripts/finalize-docs-change.sh

If significant change:

./scripts/new-change-entry.sh "Description"
# Copy output to docs/reports/change-register.md

---

Principle: Docsaurus is the Source of Truth

Docsaurus is the canonical, authoritative documentation system for all EchoHuman and Southville Forge infrastructure.

Every change to:

• Sites and services
• Server configurations
• Containers and VMs
• Deployment procedures
• Project structures
• Integrations

MUST be reflected in Docsaurus documentation.

What Docsaurus Is

• A static site generator (Docusaurus)
• Source lives on Vera at /home/southville-forge/Southville-Forge-System/Sites/docsaurus-echohuman
• Built output deployed to VM700 at /opt/stacks/echohuman-docsaurus/site-build/
• Served at https://docsaurus.echohuman.org
• Instruction files: PROJECT-BOOTSTRAP.md, AGENTS.md

What Docsaurus Is NOT

• Not a live database or CMS
• Not automatically synced from infrastructure (yet)
• "Dynamic" means generated markdown + rebuild, not real-time updates

Standard DocOps Workflow

Step 1: Pre-work Orientation

For AI agents:

• Read PROJECT-BOOTSTRAP.md first
• Read AGENTS.md second
• Identify source path, deployment path, relevant docs, inventory files
• Do not search filesystem from scratch unless necessary

For humans:

• Open docsaurus-echohuman in editor
• Review PROJECT-BOOTSTRAP.md for commands and structure

Step 2: Make the Change

Make your infrastructure/project change as needed.

Step 3: Finalize Documentation

Standard command (handles everything):

./scripts/finalize-docs-change.sh

This script:

1. Verifies you're in the Docsaurus source root
2. Runs all inventory audits (npm run docs:update -- --all)
3. Builds the site (npm run build)
4. Shows which generated files changed
5. Reminds you about change-register entry

Manual steps (if needed):

npm run docs:update -- --all  # Run all audits
npm run build                # Build site

Step 4: Update Change Register (if significant)

For significant infrastructure or project changes:

./scripts/new-change-entry.sh "Brief description"

Copy the template output and paste into docs/reports/change-register.md after the header.

What counts as significant:

• New service or website deployed
• Infrastructure configuration changed
• DNS records modified
• New repository created
• Major project reorganization

Step 5: Commit and Deploy

git add -A
git commit -m "Description of changes"

# Deploy when ready
rsync -avz --delete build/ [email protected]:/opt/stacks/echohuman-docsaurus/site-build/

What Must NEVER Be Documented

Security

NEVER commit or document:

• API keys or tokens
• Passwords or credentials
• Raw .env file contents
• Database connection strings with passwords
• SSH private keys
• Any secret or sensitive value

The audit scripts record that .env files exist but never their contents.

Available Scripts

Script	Purpose
scripts/finalize-docs-change.sh	Standard finalization — runs audits, builds, shows changes
scripts/new-change-entry.sh	Generate template for change-register.md
scripts/update-docsaurus-inventory.sh	Run selected audits (Vera/GitHub/Cloudflare)
scripts/check-docs-drift.sh	Check for uncommitted documentation drift (scheduled use)

Generated Inventory Files

File	Purpose	Regenerated By
data/inventory/vera-projects.json	Vera project inventory	--vera audit
data/inventory/github-repos.json	GitHub repository inventory	--github audit
data/inventory/cloudflare-zones.json	Cloudflare DNS inventory	--cloudflare audit
docs/vera/project-map.md	Human-readable project listing	--vera audit
docs/vera/local-repo-map.md	Git repository listing (23 repos)	--vera audit
docs/repos/github-repo-index.md	GitHub repos (38 repos)	--github audit
docs/cloudflare/cloudflare-zone-index.md	Zone overview (18 zones)	--cloudflare audit
docs/cloudflare/dns-record-map.md	Full DNS map (175 records)	--cloudflare audit
docs/reports/*-audit-latest.md	Audit summaries	All audits

Current Audit Status

Vera Audit ✅ Active

• Scans /home/southville-forge/Southville-Forge-System
• Detects 55 projects, 23 Git repositories
• Generates project map, repo map, unclassified directories

GitHub Audit ✅ Active (requires token)

• Lists 38 repositories from Maninshed account
• Cross-references with local Vera repos
• Note: Requires GITHUB_TOKEN environment variable

Cloudflare Audit ✅ Active

• Lists 18 zones, 175 DNS records
• Generates zone index and full DNS record map
• Highlights Helsinki2 records, external records, placeholders

Commands Reference

Command	Description
npm run docs:update -- --all	Run Vera + GitHub + Cloudflare audits
npm run docs:update -- --vera	Vera audit only
npm run docs:update -- --github	GitHub audit only (needs token)
npm run docs:update -- --cloudflare	Cloudflare audit only
npm run build	Build Docusaurus site
npm run start	Local dev server
npm run serve	Serve built site locally
./scripts/finalize-docs-change.sh	Standard finalization workflow
./scripts/new-change-entry.sh "desc"	Generate change entry template

Troubleshooting

Build fails after audit

• Check for malformed markdown in generated files
• Verify sidebars.js includes new directories
• Run npm run clear then rebuild

Audit misses projects

• Check SKIP_DIRS in scripts/audit-vera-projects.py
• Increase max_depth if needed
• Add detection rules for new project types

SSH timeout to Vera

• Vera may be asleep or on unstable network
• Try WireGuard connection if available
• Check 10.200.0.2 is reachable

---

Roadmap to Full Automation

Current Status ✅

• Vera audit: Active — 55 projects, 23 Git repos
• Cloudflare audit: Active — 18 zones, 175 DNS records
• GitHub audit: Active (requires token) — 38 repos
• DocOps workflow: Scripts in place
• Change tracking: Register + templates ready
• Drift detection: Script ready for scheduling

Remaining for Full Automation

Gap	Priority	Notes
Scheduled drift detection	High	Install check-docs-drift.sh via cron/systemd on Vera
Automated deployment	Medium	GitHub Actions or Vera cron to deploy on main branch changes
Docker/VM700 audit	Medium	Scan Docker stacks on VM700, list containers, services
Helsinki2/Proxmox audit	Medium	CT/VM inventory, Caddy routing map
GitHub token for CI	Medium	Secure token storage for automated GitHub audits
Expanded Cloudflare permissions	Low	Read-only tokens for Pages, Workers, Access, SSL modes
Change register automation	Low	Optional: auto-suggest entries based on detected drift

Recommended Next Steps

1. Install drift detection:

   # Add to Vera crontab (every 6 hours)
   0 */6 * * * /home/southville-forge/Southville-Forge-System/Sites/docsaurus-echohuman/scripts/check-docs-drift.sh --quiet >> /var/log/docsaurus-drift.log 2>&1

2. Enable GitHub token:

   export GITHUB_TOKEN=ghp_xxxxxxxxxxxx

3. Add VM700 audit: Extend audit scripts to SSH into VM700 and document Docker stacks

4. Add Helsinki2 audit: SSH to Helsinki2, document CTs/VMs via Proxmox API or SSH

Design Principles

• Generated docs update automatically from inventory JSON
• Curated docs (runbooks, change register) require agent/human judgment
• Drift detection reports changes; humans decide to commit/deploy
• No automatic deployment without review (safety first)