The license portal already serves public static files and exposes its effective catalog at GET /api/catalog. Documentation is therefore built as static HTML; the existing portal process, authentication, database and payment code are not modified. Generic Utils runtime code is not coupled to the documentation service.

Source ownership:

docs/public/*.md in Enelix-EMS: installation, operator guides, FAQ and pricing explanation.
docs/public/images/*.png: explicitly reviewed real Symcon screenshots, allowlisted in images.mjs.
Explicit README/interface allowlists in config.mjs: original EMS and Utils references.
Backend catalog: every monetary value, product name, SKU, term and effective VAT rate.
This directory: rendering, navigation, publication and tests.

The default source branch is develop, visibly identified as Testing. The publisher reads separate shallow bare mirrors; it never changes existing developer checkouts. All sources are pinned to the commits captured at the start of a successful run. Neither unpublished worktrees nor internal handoffs, open issues, credentials, operational notes or arbitrary new files are published.

Alternative considered: adding server-side documentation routes. Not selected: the current static mount enables this rollout without a portal restart or a new public service. A separately maintained copy of prices was rejected because it would drift from checkout. The browser refreshes the same catalog endpoint every 30 seconds while visible, on reappearance and on manual refresh.

Public routes

/docs/index.html
/docs/erste-schritte.html
/docs/installation.html
/docs/manager.html
/docs/verbraucher.html
/docs/utils.html
/docs/faq.html
/docs/preise.html
/docs/ems/*.html and /docs/utils/*.html
/docs/manifest.json: published source commits and file mappings.
/docs-status.json: last attempted/successful synchronization, no internal errors.

The portal's anonymous login screen links to documentation, FAQ and prices. Authenticated sidebar navigation additionally links to documentation and prices.

Within the EMS references, Manager remains a direct link; consumer modules and technical interfaces are nested in native, keyboard-accessible disclosure groups. The current page's group opens on the server, also without JavaScript. Search expands matching groups and restores their previous state when cleared. All page URLs remain unchanged; new references without a group stay accessible.

assets/portal-links.css contains only the added navigation styling. portal-navigation.patch records the exact additive portal HTML change; check it against the current portal before applying it and copy the stylesheet to public/docs-portal.css. Never replace the full portal HTML from another checkout.

Install and publish

Deploy the reviewed publisher files to /home/agent/services/public-docs as the unprivileged agent user. Do not copy node_modules, state, preview, QA or backups into a repository or the public directory. Install locked dependencies:

npm ci --ignore-scripts
npm test

For rendering/rollback checks without changing public pages:

node preview.mjs
node verify.mjs
node browser-test.mjs

Publication uses the existing public mount at /home/agent/services/license/public. The portal container's UID must be able to read generated directories and files. No credentials are included in the publisher: Git uses the server's preconfigured access. Never put credentials in repository URLs or public output.

Install the two supplied units through systemctl --user link, reload the user manager, start enelix-public-docs.service once and enable enelix-public-docs.timer. Only these user units are affected. The timer checks Git five minutes after completion, with at most fifteen seconds of jitter. The successful first run can take longer while fetching both repositories.

DOCS_BRANCH accepts develop, beta or main; reading a source branch does not merge or modify it. DOCS_PUBLIC_DIR and DOCS_STATE_DIR support isolated tests. Keep the chosen channel explicit in the service configuration.

Git-only operation and historical bootstrap

The production service does not enable DOCS_ALLOW_DRAFTS. All approved guides and screenshots must exist in the selected Git branch. A missing source aborts publication and preserves the last good release; deployment copies cannot silently replace deleted Git content.

The initial 2026-10-06 deployment used explicitly labelled drafts while Git publication awaited authorization. Daniel approved commit and push on the same day. The bootstrap fallback remains available only through the explicit DOCS_ALLOW_DRAFTS=true setting, including isolated previews. It reads missing sources from the deployment-only guides/ directory and labels them as drafts. Do not treat these bootstrap copies as a second long-term editing location.

When completing a bootstrap deployment, push the approved sources first, verify that publication uses their Git commits, then install the production unit without the draft setting and reload the user service manager.

Security and resilience

Markdown is rendered with pinned Marked and sanitized with sanitize-html. Raw HTML and remote images are disabled; link schemes and local mappings are restricted. Relative links to unpublished files are plain text. The existing portal CSP remains active; there is no inline JavaScript or browser-side Git credential. Every page is readable without JavaScript except the live price table, which shows an explicit notice and a catalog link in that case.

Only the exact local PNG paths in images.mjs render as screenshots. The publisher reads binary files at the same EMS commit as the guides, checks regular file type, PNG signature and dimensions, and publishes content-hashed filenames. Image hashes, dimensions and source revisions are recorded in the manifest. Missing or invalid images fail publication and preserve the last good release. Draft bootstrap images follow the same explicit opt-in as the draft guides.

Screenshot refresh is intentionally reviewed, not a live camera into Symcon. Capture through the local-only web console in a separate browser session, without saving configuration or invoking regulation. Select useful crops, inspect them for license codes, installation IDs, accounts and private plant details, then replace the approved PNGs in Git and update the dated captions. Never publish unreviewed captures automatically. Current screenshots show the demo object tree and the manager basic settings in Symcon 8.0 on 2026-10-06. Test values are not recommended installation settings; reference READMEs may evolve faster than the dated screenshots.

Publication is a complete immutable release followed by an atomic docs symlink switch. Failed fetches or rendering leave the previous release intact. Public status reports failed or overdue checks. Stale prices are removed when the catalog cannot be obtained or validated; no hardcoded fallback is used.

The sync lock prevents overlapping manual and timer runs. If the process is forcibly terminated, inspect process state before removing its stale lock from the publisher state directory. Generated releases are retained to permit rollback; disk usage should be monitored and old releases pruned only after checking that they are not current or needed for rollback.

Verification and rollback

npm test covers relative and cross-repository links, HTML sanitization, allowlist isolation, headings/tables, price validation, VAT and periods. node verify.mjs validates all published links and deliberately exercises a source failure against an isolated mirror, proving last-good preservation. node browser-test.mjs checks desktop, 390px and 320px layouts, search, automatic catalog refresh, newly returned products, VAT toggle, API failure/recovery and JavaScript-free documentation. Mocks affect only a fresh browser context, never the production catalog. Screenshots remain private in qa/.

node verify.mjs live and node browser-test.mjs --live perform anonymous checks on the actual domain. The tests must not log in or mutate live application data.

For rollback, first stop and disable only the documentation timer. Restore the previous documentation symlink atomically. For full removal, revert only the added portal navigation and stylesheet link after checking for concurrent edits; do not overwrite the portal with an older full backup if other edits occurred. No database, Nginx or IP-Symcon rollback is required because those were unchanged.

Initial deployment evidence

2026-10-06: 29 pages, 1,116 valid local links, 12 unit tests passed, isolated failure recovery passed, desktop/mobile browser tests passed both in preview and against the public domain. The initial sources were EMS 58f91e431936fedca3e59178037b939f420ce3e3 and Utils 82860c0eb938173841088f935a306729b6ce9a1c. These are dated evidence, not permanent source pins. The price API initially returned 15 products and was accessed without login.

Portal navigation backup: /home/agent/services/public-docs/backups/2026-10-06T12-58-13-558Z/index.html. The backup is private and must never be copied into public/.

Pull request summary

Add public documentation and FAQ from reviewed Git-backed sources, plus a live backend-driven price table. Preserve existing portal authentication and data; publish static releases atomically with a five-minute user timer. No schema or module migration and no beta/main changes. Include the end-user introduction, guided first steps, reviewed Symcon screenshots and grouped module navigation. Production publication requires versioned guides and screenshots, without draft fallback.