Documentation Maintenance¶

Guide for maintaining Tower Fleet documentation using OtterWiki.

Last Verified: 2025-12-08

Overview¶

Documentation is hosted on OtterWiki with automatic sync from the tower-fleet repository.

Property	Value
URL	https://otterwiki.bogocat.com
Source	`/root/tower-fleet/docs/`
Sync	Automatic (every 60 seconds via git-sync)
Auth	Authentik (SSO)
K8s Namespace	`otterwiki`

Workflow is simple: Edit markdown files → Push to GitHub → Changes appear automatically.

Adding New Pages¶

Step 1: Create the File¶

# Navigate to docs directory
cd /root/tower-fleet/docs

# Create in appropriate category
vim workflows/my-new-workflow.md
# or
vim reference/new-reference.md
# or
vim applications/new-app.md

Step 2: Add Frontmatter (Optional)¶

OtterWiki supports optional YAML frontmatter for metadata:

---
title: My Page Title
---

# My Page Title

Content here...

Step 3: Commit and Push¶

git add docs/workflows/my-new-workflow.md
git commit -m "docs: add my-new-workflow guide"
git push

Step 4: Verify (Optional)¶

Changes sync automatically within 60 seconds. To verify:

# Check git-sync logs
kubectl logs -n otterwiki deployment/otterwiki -c git-sync --tail=5

No build step. No navigation configuration. No restart required.

Editing Existing Pages¶

# Edit the file
vim /root/tower-fleet/docs/reference/some-page.md

# Commit and push
git add -A && git commit -m "docs: update some-page" && git push

Changes appear on OtterWiki within 60 seconds.

Documentation Structure¶

Current Categories¶

/root/tower-fleet/docs/
├── applications/       # App-specific docs (home-portal, money-tracker, etc.)
├── reference/          # Technical reference (conventions, configs, troubleshooting)
├── workflows/          # How-to guides (creating apps, deployments, migrations)
├── projects/           # Project design docs (specs, roadmaps, architecture)
│   ├── palimpsest/    # Solo RPG with LLM DM
│   └── trip-planner/  # AI travel planning
├── operations/         # Ops guides (Proxmox, logging, alerts)
├── getting-started/    # Onboarding and overview docs
└── archive/            # Deprecated content (preserved for reference)
    └── deprecated/     # Files moved here instead of deleted

Project Documentation¶

Project docs live directly in tower-fleet/docs/projects/<project>/ for automatic OtterWiki sync.

/root/tower-fleet/docs/projects/
└── palimpsest/            # Solo RPG with LLM DM
    ├── index.md           # Project overview with links
    ├── design/            # Active specs and roadmaps
    ├── reference/         # Architecture and conventions
    ├── analysis/          # Playtesting and quality assessment
    └── archive/           # Historical/deprecated docs

Pattern: - Docs in tower-fleet = automatic sync to OtterWiki - Add index.md with project overview and doc links - Organize into logical categories (design, reference, analysis, archive) - Project's CLAUDE.md should reference tower-fleet doc location

Why not symlinks? Symlinks don't work with GitHub Actions (the runner can't resolve local paths). Keeping docs directly in tower-fleet ensures the standard sync workflow works.

For project repos: Add a docs/README.md pointing to tower-fleet:

# Documentation Moved
Docs: https://otterwiki.bogocat.com/projects/<project>
Source: /root/tower-fleet/docs/projects/<project>/

Naming Conventions¶

Use kebab-case for filenames: my-new-guide.md
Use descriptive names: supabase-integration.md not supabase.md
Categories match folder names: workflows/ for how-to guides
Prefix ADRs with number: ADR-001-decision-name.md

OtterWiki auto-generates navigation from folder structure. No manual nav configuration needed.

To control page order, use numeric prefixes: 01-overview.md, 02-setup.md

Keeping Documentation Fresh¶

The Golden Rule¶

Every time you change infrastructure or add features, update the relevant docs.

Freshness Indicators¶

Add a "Last Verified" date to critical docs:

**Last Verified:** 2025-12-08

Update this date when you verify the content is still accurate.

Periodic Audits¶

Run the documentation audit workflow quarterly or after major changes:

Audit workflow: See /root/tower-fleet/docs/workflows/documentation-audit.md

The audit identifies: - Outdated content (stale paths, deprecated tech) - Broken commands - Orphaned pages (no references) - Missing documentation gaps

Common Staleness Patterns¶

Watch for these indicators that a doc needs updating:

Pattern	Example	Action
LXC container references	`pct exec 150`	Update to host-based workflow
Old Supabase IPs	`10.89.97.214:8001`	Verify current LoadBalancer IP
`/opt/` or `/home/` paths	`/opt/app/`	Update to `/root/projects/`
MkDocs references	`mkdocs build`	Remove (OtterWiki now)

For Claude Code¶

When to Update Docs¶

Update documentation when:

Creating new features: Document in applications/ or relevant guide
Changing infrastructure: Update affected reference docs
Fixing issues: Add to troubleshooting sections
Learning something new: Capture it for future reference

Documentation-First Pattern¶

When answering questions covered by docs, reference the doc:

"See Creating New App for the complete workflow."

This keeps docs as the source of truth and reminds users where to find info.

Commit Message Format¶

git commit -m "docs: add/update/fix description"

Examples: - docs: add otterwiki troubleshooting section - docs: update supabase URLs for sandbox - docs: fix broken link in creating-new-app

For Developers¶

Quick Reference¶

# Edit docs
cd /root/tower-fleet/docs
vim <category>/<page>.md

# Commit
git add -A && git commit -m "docs: description" && git push

# Check sync status
kubectl logs -n otterwiki deployment/otterwiki -c git-sync --tail=10

# View site
open https://otterwiki.bogocat.com

Writing Guidelines¶

Be concise: Get to the point quickly
Show examples: Code blocks > prose
Test commands: Verify commands work before documenting
Link related docs: Use relative paths [Link](../reference/other.md)
Update, don't duplicate: Modify existing docs rather than creating new ones

Archiving Content¶

When to Archive¶

Archive documentation that is: - Deprecated but potentially useful for reference - Related to removed features - Historical context that shouldn't be deleted

How to Archive¶

# Create dated archive folder
mkdir -p /root/tower-fleet/docs/archive/deprecated/2025-12

# Move the file
mv docs/old-guide.md docs/archive/deprecated/2025-12/

# Update any references
grep -r "old-guide.md" docs/ | grep -v archive

# Commit
git add -A && git commit -m "docs: archive old-guide (deprecated)" && git push

Archive vs Delete¶

Archive: Content that might be useful for historical reference
Delete: Truly obsolete content with no reference value

When in doubt, archive. Markdown files take minimal space.

Troubleshooting¶

Changes Not Appearing¶

Wait 60 seconds - git-sync polls on this interval.

Check sync status:

kubectl logs -n otterwiki deployment/otterwiki -c git-sync --tail=20

Sync Script Errors¶

Check the exechook output:

kubectl logs -n otterwiki deployment/otterwiki -c git-sync | grep exechook

Can't Access OtterWiki¶

Check pod status:
```
kubectl get pods -n otterwiki
```
Check ingress:
```
kubectl get ingress -n otterwiki
```
Check Authentik (auth issues):
```
kubectl get pods -n authentik
```

Content Formatting Issues¶

OtterWiki uses standard GitHub-flavored Markdown. If formatting looks wrong: - Check for tabs vs spaces - Verify code block language hints - Test with a markdown preview locally

Infrastructure Details¶

For OtterWiki deployment, sync configuration, and Authentik integration:

See: /root/tower-fleet/docs/applications/otterwiki.md

Key components: - K8s Deployment with git-sync sidecar - SSH key for private repo access - Authentik forward auth with custom headers - Longhorn PVC for wiki data

Documentation Audit Workflow - Periodic audit process
OtterWiki Application - Deployment details
Git Patterns - Commit conventions

Legacy Reference¶

Previously, documentation was hosted on MkDocs in LXC 411. This was migrated to OtterWiki in December 2025 for: - Simpler maintenance (no build step) - Better git integration - Automatic navigation - SSO via Authentik

The legacy LXC containers (411 for MkDocs, 117 for Wiki.js) are deprecated.