haxtheweb/haxcms-nodejs/hax-managed-files

HAX Managed Files

HAXcms distinguishes authored files (human/tool-controlled, safe to edit) from managed files (generated artifacts, rebuilt by tooling, never hand-edited). This skill lists both and the protective build rules. It exists to stop an agent from corrupting a site by editing generated output or running forbidden builds.

When to Use

• Before editing any file in a HAX site or HAXcms deployment.
• When deciding whether to run a build command.
• When choosing between the local hax CLI and npx.
• When a generated file looks wrong and the instinct is to "just fix it in place."

Authored files (safe to edit directly)

• site.json — structure and metadata. Edit via the hax CLI, not by hand, to avoid production

issues. metadata.site.name must stay aligned with the site folder name.

• pages/<item-id>/index.html — page content. This is where authored HTML lives, and it is the

only source of truth for a page's content.

• files/ — static assets (images, pdfs, uploads).
• theme/ — custom theme (theme.css + assets). For theme classes inheriting from

HAXCMSLitElement, run yarn run build after changes; do not manually edit custom-elements.json.

• custom/ — custom build layer (custom.es6.js) when present.
• docs/ — documentation (on the HAXcms docs site).

Managed files (generated — rebuild, never hand-edit)

These are produced by rebuildManagedFiles() and the ubiquity build. Editing them in place is futile (the next rebuild overwrites them) and can corrupt a site. The exceptions are the partly managed files in the next section.

• SEO / discovery: llms.txt, sitemap.xml, sitemap-index.xml, rss.xml,

atom.xml.

• Search: lunrSearchIndex.json.
• PWA: manifest.json, service-worker.js, push-manifest.json, browserconfig.xml,

offline.html.

• Registry / autoloader: wc-registry.json (built by ubiquity), build.js, build-haxcms.js.
• Static fallbacks: index.html, 404.html, ghpages.html, assets/upgrade-browser.html.
• well-known: .well-known/security.txt, .well-known/api-catalog,

.well-known/agent-skills/index.json and the agent-skills skill files.

• Config / tooling: web-dev-server.haxcms.config.cjs, files/.htaccess.
• Backend (PHP/Node): index.php, config.php (PHP); SCORM imsmanifest.xml + the *.xsd files.
• Per-page alternate formats: pages/<item-id>/index.md, index.json, index.yaml, index.xml

(and any other index.* next to index.html). They are built from index.html whenever the content changes through HAX tooling (the editor, hax site node:add / node:edit). If you edit index.html directly, they stay stale until the next content save; to update content and its alternates together, use hax site node:edit --item-id <id-or-slug> --content <file-or-html> --y --no-i.

Partly managed files (edit only outside the managed block)

HAXcms owns part of these files and the site owner owns the rest. A rebuild rewrites only HAXcms's part, and only when it changed; everything else is kept.

• Never edit inside a managed block or remove a marker. A file with only one marker left is

treated as damaged: a fresh block is added above it, and the old content is kept for the owner to clean up.

• Markers count only at the start of a line, and contain no version number.
• files/.htaccess (execution hardening for uploads) stays fully managed. Do not edit it.

When a managed file is wrong, fix the source it is generated from, then rebuild:

• llms.txt / the managed block of robots.txt / sitemap / lunrSearchIndex — regenerate via rebuildManagedFiles

(triggered by save operations or the hax CLI).

• wc-registry.json / build*.js / minified build/ assets — fix in the **webcomponents

monorepo** source, verify locally, then the user runs the ubiquity build (see below).

Protective build rules

• Never run the ubiquity script. It builds the CDN registry and distribution. The user runs it;

an agent must not, under any circumstances.

• Never run a build at the top of the webcomponents monorepo.
• Do not run traditional build commands in the monorepo — they are not used.
• Do not modify files in `build/` or `node_modules/` — change the underlying source instead.
• When fixing minified build-directory issues in the PHP or NodeJS HAXcms backends, fix the problem

in the webcomponents monorepo first. After local verification, the user runs the ubiquity build.

• When writing new HAXcms backend code (PHP/NodeJS), repurpose core data-model loading code rather

than writing new abstractions. Prefer reusing existing methods over new file-path resolution abstractions.

Use the local hax CLI, not npx

• Use the local/global hax command. Do not use npx hax — it resolves to a different package and

may be stale. The local copy is always the latest (or experimental) because the source starts on this machine.

• When automating, pass --y --no-i (and --auto / --quiet / --skip as needed) so no prompts

are asked and no new window/process launches. Without these, a command that displays the site can open a new window and hang.

New elements

• All new elements in the monorepo must be created with the hax webcomponent CLI command (not

manually) to ensure uniform demo/packaging/distribution files.

References

• Related skills: hax-site-structure (what the files are), hax-content-authoring (editing page

content), hax-site-building (creating sites).

• PRAW RULES.md: canonical ecosystem rules by Rule ID.