Operator & Codex
50a915c414
Remove the ASTRO_SITE_PATH alias and stale STRIPPED/refactor comments now that CMS_DOCS_SITE_PATH is the canonical docs project path. --- Build: pass | Tests: pass — 2372 passed (704 files) --- Build: pass | Tests: pass — 2372 passed (704 files) --- Build: pass | Tests: pass — 2372 passed (704 files) --- Build: pass | Tests: pass — 2372 passed (704 files)
16 KiB
16 KiB
Three-Bird Documentation Architecture
Status: MVP Implementation Complete (April 2026)
Goal: Codify documentation localization for Pi/Aider automation
Scope: EN + SLO (MVP), roadmap: DE/SRB/CRO/BIH/RU/ZN/BR
Overview
The three-bird architecture decouples documentation concerns into three independent systems that work together:
- 🐦 Crowdin — Localization source of truth. Single English source, managed translations in 9 languages.
- 🐦 Astro Starlight — Static site generator. Builds multilingual docs from Crowdin translations + English.
- 🐦 Strapi CMS (deferred) — Content backend for rich media/structured content. Blocked by FreeBSD native binding issues at the time of this design; revisit if Strapi support is reconsidered.
Architecture Diagram
┌─────────────────────────────────────────────────────────────────┐
│ ENGLISH SOURCE DOCS │
│ docs/public/**.md (repo) │
│ │
│ - install/ - architecture/ │
│ - reference/ - getting-started/ │
│ - api/ - troubleshooting/ │
└────────────────────────────┬────────────────────────────────────┘
│
┌────────▼────────┐
│ Crowdin Push │
│ (./scripts/ │
│ crowdin-sync │
│ .sh --push) │
└────────┬────────┘
│
┌───────────────────┼───────────────────┐
│ │ │
│ ┌─────▼──────┐ │
│ │ Crowdin │ │
│ │ Localization│ │
│ │ Platform │ │
│ │ (883714) │ │
│ └─────┬──────┘ │
│ │ │
┌────────▼────────┐ ┌──────▼──────┐ ┌────────▼────────┐
│ Slovenian (SLO) │ │ German (DE) │ │ Croatian (HR) │
│ 100% default │ │ Roadmap │ │ Roadmap │
└────────┬────────┘ └──────┬──────┘ └────────┬────────┘
│ │ │
└──────────────────┼───────────────────┘
│
┌──────────▼──────────┐
│ Crowdin Pull │
│ (./scripts/ │
│ crowdin-sync │
│ .sh --pull) │
└──────────┬──────────┘
│
┌──────────────────┼──────────────────┐
│ │ │
┌────▼────┐ ┌────▼────┐ ┌────▼────┐
│docs/ │ │docs/ │ │docs/ │
│public/ │ │public/ │ │public/ │
│sl/ │ │de/ │ │hr/ │
└────┬────┘ └────┬────┘ └────┬────┘
│ │ │
└──────────────────┼──────────────────┘
│
┌────────────────▼────────────────┐
│ Astro Starlight Build │
│ (npm run build in │
│ bootstrap/cms/clawdie-docs/) │
│ │
│ - Multi-locale config │
│ - Sidebar i18n │
│ - Static site generation │
└────────────────┬────────────────┘
│
┌────────────────▼────────────────┐
│ Static Site Output │
│ (dist/) │
│ │
│ / (SLO) │
│ /en/ (English) │
│ /de/ (German) │
│ /hr/ (Croatian) │
│ ... (others) │
└────────────────┬────────────────┘
│
┌────────────────▼────────────────┐
│ Deploy to nginx │
│ (/usr/local/www/clawdie/docs) │
└────────────────┬────────────────┘
│
┌────────────────▼────────────────┐
│ PUBLIC: docs.clawdie.si │
└─────────────────────────────────┘
MVP Decision: Markdown-Only (Option A)
Chosen Approach: Ship with Crowdin + Astro (no Strapi for now)
Why Markdown-Only First
| Factor | Markdown-Only | Strapi Path |
|---|---|---|
| Shipping time | 1-2 weeks | 3-4 weeks |
| Dependencies | Standard tools | FreeBSD blocker |
| MVP feature set | ✓ Full (docs + translations) | ✗ Incomplete (no image upload) |
| Maintenance | Simple (pure markdown) | Complex (CMS + API) |
| Codifiable for Pi | ✓ Yes | ⚠ Conditional |
What Ships in MVP
✓ Crowdin localization platform (LIVE)
✓ Markdown sources in docs/public/
✓ Automated Crowdin → Astro pipeline
✓ Multi-language static site
✓ English (EN) + Slovenian (SLO) default
✓ Roadmap languages configured (not translated yet)
✓ Pi/Aider automation for sync & deploy
What Defers (Phase 2+)
✗ Strapi CMS (blocked by FreeBSD native bindings)
✗ Rich media uploads (requires Strapi + sharp image processing)
✗ Structured content types (Page, Guide, BlogPost)
✗ CMS-driven updates (once Strapi is viable)
Implementation Status
✓ Complete
| Component | Location | Status |
|---|---|---|
| Crowdin Script | ./scripts/crowdin-sync.sh |
✓ Working (push/pull/status) |
| Crowdin Config | .crowdin.yml |
✓ Configured (project 883714) |
| English Source Docs | docs/public/**/*.md |
✓ 42+ files ready |
| Skill Documentation | .agent/skills/docs-localization-pipeline/SKILL.md |
✓ Complete |
| Setup Script | .agent/skills/docs-localization-pipeline/setup-clawdie-docs.sh |
✓ Tested |
| Pipeline Orchestrator | .agent/skills/docs-localization-pipeline/orchestrate-pipeline.sh |
✓ Ready |
| Skill README | .agent/skills/docs-localization-pipeline/README.md |
✓ Complete |
⏳ Pending (User Action)
| Task | Owner | Timeline |
|---|---|---|
| Create Crowdin translators | User | ASAP |
| Push English sources to Crowdin | Pi/Aider | This week |
| Assign translation languages | Translators | This week |
| Reach 80% completion milestone | Translators | 1-2 weeks |
| First pull & build | Pi/Aider | After milestone |
| Deploy to docs.clawdie.si | Pi/Aider | After build |
| Setup weekly sync schedule | Pi/Aider | Ongoing |
How It Works
Daily Workflow (Codified for Pi/Aider)
# 1. English docs are edited in /docs/public/**.md
# 2. Crowdin sync pushed (via Pi or cron)
./scripts/crowdin-sync.sh --push
# 3. Crowdin translators update translations
# 4. Weekly sync pulls translations
./scripts/crowdin-sync.sh --pull
# 5. Astro builds multilingual site
cd /home/clawdie/clawdie-ai/bootstrap/cms/clawdie-docs && npm run build
# 6. Deploy to nginx
sudo cp -r dist/* /usr/local/www/clawdie/docs/
sudo nginx -s reload
Automated by Pi/Aider:
pi "sync translations and rebuild documentation site"
# → Executes: orchestrate-pipeline.sh --all
Configuration Codification
All automation is controlled by environment variables in .env:
# Crowdin API token
CROWDIN_PERSONAL_TOKEN=tskey-xxx
# Paths
CMS_DOCS_SITE_PATH=/home/clawdie/clawdie-ai/bootstrap/cms/clawdie-docs
DOCS_DEPLOY_TARGET=/usr/local/www/clawdie/docs
# Thresholds
DOCS_MIN_COMPLETION=80 # Min % before auto-deploy
File Structure
Skill Assets
.agent/skills/docs-localization-pipeline/
├── SKILL.md # Detailed architecture & reference
├── README.md # Quick start & troubleshooting
├── setup-clawdie-docs.sh # Bootstrap Astro project
└── orchestrate-pipeline.sh # Full pipeline automation
Documentation
doc/
├── THREE-BIRD-ARCHITECTURE.md # This file (overview)
└── [other docs]
docs/public/ # English source
├── install/
├── architecture/
├── reference/
└── [content sections]
docs/public/{lang}/ # Crowdin translations
├── en/ # English
├── de/ # German (roadmap)
├── hr/ # Croatian (roadmap)
└── [others]
Astro Project
/home/clawdie/clawdie-ai/bootstrap/cms/clawdie-docs/
├── astro.config.mjs # Multi-locale Starlight config
├── package.json
├── src/
│ ├── content/
│ │ ├── config.ts # Content collections
│ │ ├── docs/
│ │ │ ├── en → docs/public/en (symlink)
│ │ │ ├── de → docs/public/de (symlink)
│ │ │ └── [others]
│ │ └── i18n/
│ │ ├── en.json
│ │ ├── de.json
│ │ └── sl.json
│ ├── components/
│ └── styles/
└── dist/ # Build output (after npm run build)
Integration with clawdie-ai Controlplane
Config Values (src/config.ts)
// CMS/Docs paths
export const CMS_JAIL_IP = envConfig.WARDEN_CMS_IP || '10.0.0.4';
export const CMS_DOCS_SITE_PATH =
envConfig.CMS_DOCS_SITE_PATH ||
'/home/clawdie/clawdie-ai/bootstrap/cms/clawdie-docs';
export const CMS_WEBROOT = envConfig.CMS_WEBROOT || '/usr/local/www/clawdie';
// Used by jail runtime for mounting docs build
Jail Networking
10.0.0.3 = db (PostgreSQL)
10.0.0.4 = cms (Strapi later, Astro build for now)
10.0.0.7 = web (nginx)
nginx serves:
- / → docs.clawdie.si (from Astro build)
- /api → Strapi (when available)
Phase 2: Strapi CMS Integration (Deferred)
Why Deferred
FreeBSD lacks prebuilt binaries for native Node.js modules that Strapi depends on:
sharp(image processing)esbuild(bundling)@swc/core(transpilation)
Workaround: Compile libvips from /usr/ports/graphics/vips (2-3 hours on first build).
Recommendation: Ship MVP first, add Strapi later when image upload is needed.
What Strapi Will Add
Enhanced CMS Features:
✓ Rich media upload (images, videos)
✓ Structured content types (Page, Guide, BlogPost)
✓ API endpoints for dynamic content
✓ Built-in user authentication
✓ Content versioning & publishing workflow
Integration:
- Crowdin syncs content to Strapi API
- Astro queries Strapi for rich media
- CMS-driven metadata (authors, dates, categories)
Automation Examples
Example 1: Manual Full Pipeline
# One-command deployment
./.agent/skills/docs-localization-pipeline/orchestrate-pipeline.sh --all
Example 2: Scheduled Weekly Sync
# Add to crontab
0 9 * * MON /home/clawdie/clawdie-ai/.agent/skills/docs-localization-pipeline/orchestrate-pipeline.sh --pull
Example 3: Pi/Aider Orchestration
# Natural language command
pi "Update documentation translations and rebuild the site"
# Aider auto-commit
aider --auto-commits \
--message "Sync translations from Crowdin" \
"docs/public/"
Example 4: GitHub Actions
See .github/workflows/crowdin-sync.yml (optional CI/CD).
Success Metrics
MVP Launch
- Crowdin project 883714 has English sources uploaded
- Translators assigned to at least SLO + EN
orchestrate-pipeline.sh --allproduces live site at docs.clawdie.si- Pi can execute:
pi "sync and rebuild docs" - Weekly automation in place
Phase 2 (Post-MVP)
- DE, HR, SR translations at 80%+
- Automated weekly syncs running
- Strapi ready (libvips compiled)
- CMS content integration tested
Quick Links
| Resource | Path | Purpose |
|---|---|---|
| Skill | .agent/skills/docs-localization-pipeline/ |
Executable automation |
| Architecture Doc | doc/THREE-BIRD-ARCHITECTURE.md |
This file |
| Crowdin Sync Script | ./scripts/crowdin-sync.sh |
Manual push/pull/status |
| Crowdin Config | .crowdin.yml |
Project settings |
| AGENTS.md | AGENTS.md |
Pi/Aider harness guidance |
| Astro Example | examples/astro-cv/ |
Reference Starlight setup |
References
- Crowdin: https://crowdin.com/project/clawdie-ai
- Astro Starlight: https://starlight.astro.build/
- Crowdin API: https://developer.crowdin.com/api/