Skip to content

Updating the Documentation

Source of truth

The private GitHub repository 29w211barnes/barnesbears-docs is authoritative. Do not edit /var/www/barnesbears-docs directly: generated files are overwritten by the next build.

The source layout includes mkdocs.yml, requirements.txt, and Markdown under docs/. Navigation is explicitly configured in mkdocs.yml: add new pages to its nav section so they appear in the sidebar.

Method 1 — Browser editing

  1. Open the private GitHub repository.
  2. Navigate to a Markdown file under docs/.
  3. Choose Edit (pencil icon), make the changes, and preview.
  4. Commit to a branch and open a pull request for review (recommended). For small trusted changes, committing to main also works.
  5. Once merged to main, the LXC pulls and publishes it at the next timer run (roughly five minutes).

Images should be committed under docs/assets/images/ and linked using relative Markdown paths. Never commit secrets, tokens, private keys, or recovery credentials.

Method 2 — ChatGPT

ChatGPT has been connected to the Barnes Bears GitHub account and has successfully edited docs/index.md. Ask it to create or update a documentation page and, when appropriate, the navigation in mkdocs.yml.

For important changes, ask for a branch and pull request rather than a direct commit to main. Review technical assertions before merging. GitHub integration availability can vary by session.

Method 3 — Wadsworth

Wadsworth (the OpenClaw home-automation agent) has write access to this repository through its own SSH deploy key, added in October 2026.

Property Value
Credential Repository deploy key titled wadsworth, write access enabled
Key fingerprint SHA256:4FOUtPYNxJLk2Ma6+V/sOpmyi6ToEWof+Vqe//svOv0 (ED25519)
Scope This repository only; no other repositories or GitHub API access
Key location Wadsworth's OpenClaw workspace on the OpenClaw host (192.168.10.172)
Commit identity Wadsworth <wadsworth@openclaw.local>

Workflow:

  1. Wadsworth checks the relevant pages and verifies technical claims against live systems where it has read access (Frigate API, Home Assistant via the ha-ro read-only route).
  2. It cuts a fresh wadsworth/<topic> branch from the latest main.
  3. It validates the change with mkdocs build --strict using the versions pinned in requirements.txt.
  4. It pushes the branch. A deploy key cannot open pull requests, so a human opens the PR from GitHub's "Compare & pull request" banner, reviews, and merges.
  5. The docs LXC publishes the merged version at the next timer run.

Rules Wadsworth follows:

  • Never pushes to main, never force-pushes, and never modifies or deletes branches it did not create. GitHub does not enforce branch protection on this repository's plan, so these are Wadsworth's own rules; review merged history if in doubt.
  • Never commits secrets, tokens, private keys, or authorization headers.
  • Never commits camera images, snapshots, event details, or Home Assistant state dumps. Pages document how systems are set up, not household activity.

Revoking access: delete the wadsworth key under the repository's Settings → Deploy keys. Any of Wadsworth's changes can be reverted like any other commit.

Do not give Wadsworth the docs LXC's deploy key: that key is intentionally read-only and separate.

How publication works

The barnesbears-docs-update.timer invokes barnesbears-docs-update.service, which runs /usr/local/sbin/update-barnesbears-docs.

The initial deployed script:

#!/bin/bash
set -euo pipefail

REPO="/opt/barnesbears-docs"
SITE="/var/www/barnesbears-docs"
MKDOCS="/opt/mkdocs-venv/bin/mkdocs"

cd "$REPO"
git fetch origin main
LOCAL=$(git rev-parse HEAD)
REMOTE=$(git rev-parse origin/main)

if [ "$LOCAL" = "$REMOTE" ]; then
    echo "Documentation already up to date."
    exit 0
fi

git merge --ff-only origin/main
"$MKDOCS" build --clean --site-dir "$SITE"
echo "Documentation updated successfully."

The systemd timer was configured with OnBootSec=2min, OnUnitInactiveSec=5min, and Persistent=true.

Force an update or troubleshoot

systemctl start barnesbears-docs-update.service
journalctl -u barnesbears-docs-update.service -n 50 --no-pager
systemctl list-timers barnesbears-docs-update.timer

Check Git and local version:

cd /opt/barnesbears-docs
git status --short
git log -1 --oneline
git rev-parse origin/main

If the build fails, run it manually for the full error:

cd /opt/barnesbears-docs
/opt/mkdocs-venv/bin/mkdocs build --clean --site-dir /tmp/barnesbears-docs-test --strict

The test build writes to /tmp so it does not overwrite the published site.

Branding

The BarnesBears bear icon should be stored as docs/assets/images/barnesbears-docs.png. The site configuration references it using theme.logo and theme.favicon (paths relative to docs/). Do not enable those references until the PNG has been uploaded to GitHub.

Dependency upgrades

Versions are intentionally constrained to MkDocs 1.x and Material 9.x in requirements.txt. Test any dependency upgrades before applying them to the LXC:

/opt/mkdocs-venv/bin/pip install -r /opt/barnesbears-docs/requirements.txt

Consider Zensical as a future alternative; do not upgrade to MkDocs 2.x without a deliberate compatibility review.