clawdie-ai/docs/internal/DOCUMENTATION.md

Documentation System

Last Updated: 27.apr.2026

Part 1: Policy & Sources

Canonical Sources

Clawdie currently has two public docs tracks:

• docs/public/ — the canonical markdown source for the current install, architecture, operate, reference, roadmap, and localization docs
• html/docs-clawdie-si/ — legacy bridge content from the earlier static docs site

Rules:

• prefer editing markdown in docs/public/ for current product docs
• treat the checked-in html/docs-clawdie-si/ tree as bridge material, not the long-term authored source
• do not treat old host-side docs-current notes as the live serving path for docs.clawdie.si

Deployment Targets

Target	URL	Source	Notes
docs.clawdie.si	https://docs.clawdie.si	Astro/Starlight deploy in cms jail	Live public docs surface
osa.smilepowered.org	https://osa.smilepowered.org	repo-managed static site	separate surface
clawdie.si	https://clawdie.si	repo-managed marketing site	separate surface

Content Classification

Public:

• docs/public/ — operator guides and product docs

Internal:

• docs/internal/ — technical internals, plans, session logs
• .env.example — secrets template, not published

Version Control

Commit:

• markdown source files
• sync scripts
• nginx configs
• deployment notes

Do not commit:

• generated HTML build output
• live symlinks
• log files
• lock files

Part 2: Live Serving Model

Architecture

public request https://docs.clawdie.si
  -> host nginx TLS / edge
  -> proxy to cms jail (10.0.1.4)
  -> jail nginx
  -> /usr/local/www/clawdie
  -> Astro/Starlight static export

Components:

1. host nginx terminates public TLS and forwards the docs hostname
2. cms jail nginx serves the deployed static site
3. live webroot is /usr/local/www/clawdie inside the cms jail
4. the older /usr/local/www/docs.clawdie.si host tree still exists as bridge content / ACME support, but it is not the active HTTPS docs surface

Quick Reference

Task	Command
Inspect live edge vhost	sudo sed -n '1,220p' /usr/local/etc/nginx/vhosts/docs.clawdie.si.conf
Inspect cms jail nginx	sudo bastille cmd cms cat /usr/local/etc/nginx/nginx.conf
Inspect live docs webroot	sudo bastille cmd cms ls -la /usr/local/www/clawdie
Inspect live homepage	sudo bastille cmd cms sed -n '1,40p' /usr/local/www/clawdie/index.html
Verify public response headers	curl -I https://docs.clawdie.si

Legacy Notes

These older pieces still exist in the repo and may be useful as migration references, but they do not describe the current public serving path:

• scripts/docs-compile.sh
• scripts/docs-sync.cron.sh
• /usr/local/www/docs.clawdie.si
• docs-current / docs-v* rollback notes

If those are revived later, document them as an explicit legacy or migration path instead of the default docs runtime.

Part 3: Editing Workflow

Adding a New Public Document

1. create the markdown source in docs/public/
2. keep naming and surface language aligned with the multitenant naming policy
3. if a legacy HTML page still mirrors the same content, either update it deliberately or mark it as archived/bridge content

Adding a New Internal Document

1. create docs/internal/TOPIC.md
2. keep it in git; do not treat it as a public page

Pre-Commit Guard

hooks/pre-commit should continue to block accidental generated HTML in the markdown docs source tree:

if git diff --cached --name-only | grep '^docs/public/.*\.html$'; then
  echo "ERROR: HTML files must not be committed to docs/public/"
  exit 1
fi