Wiki Documentation Lifecycle Workflow

Complete guide for updating and deploying the PermitProof documentation wiki.

📝 Quick Reference

Daily Workflow (Most Common)

# 1. Edit docs
vim docs/tdd/production-readiness.md

# 2. Commit
git commit -m "Update docs"

# 3. Smart deploy (auto-syncs + auto-detects rebuild)
./cli/sdlc/wiki/deploy-to-firebase-smart.sh  # ⚡ 10-40 sec
# Note: This script automatically syncs docs/ first, then builds if needed

When to Use Each Command

Command	When to Use	Time	What It Does
`deploy-to-firebase-smart.sh`	⭐ 99% of docs updates	~10-40s	Auto-syncs + auto-detects if rebuild needed
`deploy-to-firebase.sh --skip-functions`	Force rebuild	~30-60s	Build + deploy hosting only
`deploy-to-firebase.sh` (no flags)	Allowlist changes	~3-4 min	Full deployment with functions
`rebuild-wiki.sh`	⚠️ Dependency issues ONLY	~2-3 min	Clears `node_modules` + reinstalls (does NOT deploy)

Important: rebuild-wiki.sh is NOT for regular deployments! It only refreshes dependencies when you have corruption or need to update packages. After running it, you still need to run a deploy command.

📋 Complete Lifecycle

Step 1: Edit Documentation

Edit any markdown files in the docs/ folder:

vim docs/tdd/production-readiness.md
# or create new
vim docs/new-feature-guide.md

Step 2: Commit Changes (Auto-Syncs)

git add docs/
git commit -m "Update production readiness documentation"

What happens automatically:

Post-commit hook runs
     ↓
Detects changes in docs/
     ↓
Runs sync-docs-to-wiki.sh
     ↓
rsync docs/ → wiki/docs/
     ↓
Shows deployment reminder

Step 3: Deploy (Choose Your Speed)

⚡ Smart Deploy (Recommended for Docs Updates)

./cli/sdlc/wiki/deploy-to-firebase-smart.sh

Time: ~10-40 seconds (depending on if rebuild needed)

Smart features:

🔄 Auto-syncs docs/ to wiki/docs/ first
🧠 Auto-detects if docs changed since last build
⏭️ Skips rebuild if docs unchanged (~10-20s)
✅ Rebuilds if docs changed (~30-40s)
⏭️ Always skips Cloud Functions

Use --force to force rebuild even if docs haven't changed.

🔧 Full Deploy (When Allowlist Changes)

./cli/sdlc/wiki/deploy-to-firebase.sh

Time: ~3-4 minutes

Includes everything:

✅ Cloud Functions TypeScript compile
✅ Cloud Functions deployment
✅ Docusaurus build
✅ Firebase Hosting deployment

Use when you've modified:

wiki/functions/src/index.ts (allowlist changes)
wiki/src/theme/Root.tsx (auth logic changes)

⚡ Performance Optimizations

1. Docusaurus Build Caching

Docusaurus automatically caches builds in .docusaurus/ folder:

First build: ~10-15 seconds
Incremental builds: ~5-8 seconds (only changed files)
Clean build: Delete .docusaurus/ to force full rebuild

# Force clean build (rarely needed)
cd wiki
rm -rf .docusaurus
npm run build

2. Skip Functions for Speed

99% of the time, you're just updating documentation, not the allowlist.

Use --skip-functions to save 2-3 minutes:

# Before (slow)
./cli/sdlc/wiki/deploy-to-firebase.sh  # 3-4 minutes

# After (fast)
./cli/sdlc/wiki/deploy-to-firebase.sh --skip-functions  # 30-60 seconds

3. Skip Build for Hotfixes

If you've already built and just need to redeploy:

./cli/sdlc/wiki/deploy-to-firebase.sh --skip-build --skip-functions  # ~10-20s

🔄 Auto-Deploy Options

Manual Deploy (Default - Recommended)

# Commit syncs docs
git commit -m "Update docs"

# Deploy manually when ready
./cli/sdlc/wiki/deploy-to-firebase.sh --skip-functions

Pros:

✅ Control over what gets published
✅ Can preview locally before deploying
✅ Batch multiple commits before deploying

Auto-Deploy (Optional)

Enable in your shell profile (~/.bashrc or ~/.zshrc):

export AUTO_DEPLOY_FIREBASE=true

Then every commit to docs/ automatically:

Syncs to wiki
Builds Docusaurus
Deploys to Firebase

Pros:

✅ Hands-free, always up-to-date
✅ No manual deployment step

Cons:

⚠️ Every commit goes live immediately
⚠️ Can't preview before publishing

📊 Deployment Time Breakdown

Full Deployment (~3-4 minutes)

Cloud Functions build:    ~30s
Cloud Functions deploy:   ~2-3 min  ← Slowest part
Docusaurus build:         ~30-40s
Firebase Hosting deploy:  ~10-20s
──────────────────────────────────
Total:                    ~3-4 min

Fast Deployment (~30-60 seconds)

Cloud Functions: SKIPPED ← Saves 2-3 min!
Docusaurus build:         ~30-40s
Firebase Hosting deploy:  ~10-20s
──────────────────────────────────
Total:                    ~30-60s

🎯 Recommended Workflows

For Different Use Cases

Regular Doc Updates (95% of commits):

git commit -m "Update docs"
./cli/sdlc/wiki/deploy-to-firebase.sh --skip-functions  # ⚡ Fast

Adding Users to Allowlist:

# Edit wiki/functions/src/index.ts
git commit -m "Add user to wiki allowlist"
./cli/sdlc/wiki/deploy-to-firebase.sh  # 🔧 Full (no flags)

Urgent Hotfix (Already Built):

# Fix typo directly in wiki/docs/
./cli/sdlc/wiki/deploy-to-firebase.sh --skip-build --skip-functions  # ⚡⚡ Super fast

Preview Before Deploy:

git commit -m "Update docs"
cd wiki && npm start  # Preview at localhost:3000
# If looks good:
./cli/sdlc/wiki/deploy-to-firebase.sh --skip-functions

🔗 Command Reference

# Deployment (Daily Use)
./cli/sdlc/wiki/deploy-to-firebase-smart.sh              # ⭐ RECOMMENDED: Smart deploy (auto-sync + auto-build)
./cli/sdlc/wiki/deploy-to-firebase-smart.sh --force      # Force rebuild even if docs unchanged
./cli/sdlc/wiki/deploy-to-firebase.sh --skip-functions   # Fast deploy (force rebuild)
./cli/sdlc/wiki/deploy-to-firebase.sh                    # Full deploy (with functions)
./cli/sdlc/wiki/deploy-to-firebase.sh --skip-build       # Skip Docusaurus build
./cli/sdlc/wiki/deploy-to-firebase.sh --help             # Show all options

# Manual sync (without commit)
./cli/sdlc/wiki/sync-docs-to-wiki.sh                     # Syncs docs/ to wiki/docs/ with MDX escaping

# Local preview
cd wiki && npm start                                      # Opens localhost:3000

# Dependency Management (Rarely Needed!)
./cli/sdlc/wiki/rebuild-wiki.sh                          # ⚠️ ONLY for dependency issues
                                                         # Deletes node_modules + reinstalls
                                                         # Does NOT sync docs or deploy!

When to use rebuild-wiki.sh:

❌ NOT for regular doc updates
❌ NOT when docs change
✅ ONLY when you have npm dependency corruption
✅ ONLY when you need to update package.json dependencies
✅ ONLY when Docusaurus build fails with module errors

After running rebuild-wiki.sh, you still need to run a deployment command!

💡 Pro Tips

Use --skip-functions by default - Only deploy functions when allowlist changes
Preview locally first - Run npm start to check changes before deploying
Batch commits - Make several doc updates, then deploy once
Check build cache - .docusaurus/ makes incremental builds fast
Monitor deployment - Firebase shows progress and completion status

🐛 Troubleshooting

Deployment taking too long?

# Use smart deploy (recommended) - only rebuilds if docs changed
./cli/sdlc/wiki/deploy-to-firebase-smart.sh

# Or skip functions for docs-only updates
./cli/sdlc/wiki/deploy-to-firebase.sh --skip-functions

Build is slow?

Docusaurus caches builds automatically. First build is slow, subsequent builds are faster.

# Check cache exists
ls -la wiki/.docusaurus/

# If corrupted, delete and rebuild
rm -rf wiki/.docusaurus
npm run build

Module/dependency errors?

Symptoms:

Module not found errors
Cannot find package errors
Build fails with npm/node errors

Solution:

# 1. Rebuild dependencies (deletes node_modules and reinstalls)
./cli/sdlc/wiki/rebuild-wiki.sh

# 2. Then deploy normally
./cli/sdlc/wiki/deploy-to-firebase-smart.sh

MDX syntax errors (like `{variable} is not defined`)?

Symptoms:

Wiki page shows "This page crashed"
Browser console shows {file_id} is not defined or similar

Cause: Curly braces in docs are treated as JSX variables by MDX

Solution: The sync-docs-to-wiki.sh script automatically escapes these. If you see this error:

# 1. The escape script was already updated to handle {variable} patterns
# 2. Just redeploy - it will auto-escape
./cli/sdlc/wiki/deploy-to-firebase-smart.sh

The script escapes patterns like {file_id}, {projectId}, etc. to \{file_id\}, \{projectId\} automatically.

Functions failing to deploy?

Functions rarely change. If deployment fails:

# Deploy functions separately
cd wiki/functions
npm run build
firebase deploy --only functions:checkWikiAccess --project construction-code-expert-dev

📈 Expected Performance

Build Times (With Cache)

Build Type	Time	When
First build	~10-15s	After `npm install` or cache clear
Incremental	~5-8s	Normal docs updates
No changes	~3-5s	Rebuild same content

Deployment Times

Type	Time	Frequency
Functions	~2-3 min	Rare (allowlist changes only)
Hosting	~10-20s	Every docs update
Total (full)	~3-4 min	Initial + allowlist changes
Total (fast)	~30-60s	Regular docs updates

🎯 TL;DR - The Playbook

For 99% of doc updates:

# 1. Edit & commit (IDE or terminal)
git commit -m "Update docs"

# 2. Smart deploy (auto-detects changes)
./cli/sdlc/wiki/deploy-to-firebase-smart.sh

# Done! ✅ Live in 10-40 seconds

For allowlist updates:

# Edit wiki/functions/src/index.ts
git commit -m "Add user to allowlist"
./cli/sdlc/wiki/deploy-to-firebase.sh  # Full deploy

Simple as that! 🚀

📝 Quick Reference​

Daily Workflow (Most Common)​

When to Use Each Command​

📋 Complete Lifecycle​

Step 1: Edit Documentation​

Step 2: Commit Changes (Auto-Syncs)​

Step 3: Deploy (Choose Your Speed)​

⚡ Smart Deploy (Recommended for Docs Updates)​

🔧 Full Deploy (When Allowlist Changes)​

⚡ Performance Optimizations​

1. Docusaurus Build Caching​

2. Skip Functions for Speed​

3. Skip Build for Hotfixes​

🔄 Auto-Deploy Options​

Manual Deploy (Default - Recommended)​

Auto-Deploy (Optional)​

📊 Deployment Time Breakdown​

Full Deployment (~3-4 minutes)​

Fast Deployment (~30-60 seconds)​

🎯 Recommended Workflows​

For Different Use Cases​

🔗 Command Reference​

💡 Pro Tips​

🐛 Troubleshooting​

Deployment taking too long?​

Build is slow?​

Module/dependency errors?​

MDX syntax errors (like {variable} is not defined)?​

Functions failing to deploy?​

📈 Expected Performance​

Build Times (With Cache)​

Deployment Times​

🎯 TL;DR - The Playbook​