gethtmlpress 0.0.0-stage → 0.1.0

package/LICENSE.md

@@ -0,0 +1,9 @@
+# The MIT License (MIT)
+
+Copyright © 2026 Evgeny Karev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,49 @@
-# Temporary Holding Version
+# Htmlpress
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Htmlpress turns a folder of HTML pages into a site. Each page keeps its own markup, and
+htmlpress adds one layout, one theme, a navigation and a live-reloading dev server. It is
+made for coding agents: they write plain semantic HTML, and the result looks consistent
+without a framework, a build config or Tailwind.
+
+## Installation
+
+```bash
+npm install --global gethtmlpress
+# or run it without installing
+npx gethtmlpress build docs
+```
+
+The package carries a prebuilt binary for Linux, macOS and Windows (x64 and arm64)
+through a platform-specific optional dependency; no Rust toolchain is needed.
+
+## Usage
+
+```bash
+htmlpress build docs        # render docs/ into docs/.htmlpress/build
+htmlpress start docs        # serve it on http://localhost:8000, rebuilding on save
+htmlpress build docs --json # the result as JSON, for scripts and agents
+htmlpress --llms            # every command's input and output schema, for agents
+```
+
+A page is any `.html` file in the folder: a full document or just a fragment. Its `<title>`
+(else its first `<h1>`) names it in the navigation, `<meta name="order" content="1">` sorts it,
+and `index.html` comes first. Every other file is copied as-is.
+
+```html
+<title>Getting started</title>
+<meta name="order" content="1" />
+
+<h1>Getting started</h1>
+<p>Plain HTML, styled by the built-in theme.</p>
+<htmlpress-callout type="warning"
+  ><p>Light-DOM components cover what HTML lacks.</p></htmlpress-callout
+>
+```
+
+## Documentation
+
+Read the docs at [htmlpress.dev](https://htmlpress.dev), themselves built with htmlpress.
+
+## License
+
+MIT.

package/build/actions/binary/resolve.d.ts

@@ -0,0 +1,7 @@
+/** Find the htmlpress binary: the env override first, else the matching platform package. */
+export declare function resolveBinary(props: {
+    platform: string;
+    arch: string;
+    env: Record<string, string | undefined>;
+    resolvePackage: (specifier: string) => string;
+}): string;

package/build/actions/binary/resolve.js

@@ -0,0 +1,22 @@
+import { BINARY_ENV, PACKAGE_NAME, PLATFORMS } from "../../settings.js";
+/** Find the htmlpress binary: the env override first, else the matching platform package. */
+export function resolveBinary(props) {
+    const override = props.env[BINARY_ENV];
+    if (override)
+        return override;
+    const key = `${props.platform}-${props.arch}`;
+    const platform = PLATFORMS[key];
+    if (!platform) {
+        const supported = Object.keys(PLATFORMS).join(", ");
+        throw new Error(`${PACKAGE_NAME} has no binary for ${key}; supported: ${supported}. ` +
+            `Set ${BINARY_ENV} to a binary built with cargo to run it anyway.`);
+    }
+    try {
+        return props.resolvePackage(`${platform.packageName}/bin/${platform.binary}`);
+    }
+    catch {
+        throw new Error(`${platform.packageName} is not installed. Reinstall ${PACKAGE_NAME} without ` +
+            `--no-optional / --omit=optional so the binary for ${key} comes along.`);
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicmVzb2x2ZS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uL2FjdGlvbnMvYmluYXJ5L3Jlc29sdmUudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxFQUFFLFVBQVUsRUFBRSxZQUFZLEVBQUUsU0FBUyxFQUFFLE1BQU0sbUJBQW1CLENBQUE7QUFFdkUsNkZBQTZGO0FBQzdGLE1BQU0sVUFBVSxhQUFhLENBQUMsS0FLN0I7SUFDQyxNQUFNLFFBQVEsR0FBRyxLQUFLLENBQUMsR0FBRyxDQUFDLFVBQVUsQ0FBQyxDQUFBO0lBQ3RDLElBQUksUUFBUTtRQUFFLE9BQU8sUUFBUSxDQUFBO0lBRTdCLE1BQU0sR0FBRyxHQUFHLEdBQUcsS0FBSyxDQUFDLFFBQVEsSUFBSSxLQUFLLENBQUMsSUFBSSxFQUFFLENBQUE7SUFDN0MsTUFBTSxRQUFRLEdBQUcsU0FBUyxDQUFDLEdBQUcsQ0FBQyxDQUFBO0lBQy9CLElBQUksQ0FBQyxRQUFRLEVBQUUsQ0FBQztRQUNkLE1BQU0sU0FBUyxHQUFHLE1BQU0sQ0FBQyxJQUFJLENBQUMsU0FBUyxDQUFDLENBQUMsSUFBSSxDQUFDLElBQUksQ0FBQyxDQUFBO1FBQ25ELE1BQU0sSUFBSSxLQUFLLENBQ2IsR0FBRyxZQUFZLHNCQUFzQixHQUFHLGdCQUFnQixTQUFTLElBQUk7WUFDbkUsT0FBTyxVQUFVLGlEQUFpRCxDQUNyRSxDQUFBO0lBQ0gsQ0FBQztJQUNELElBQUksQ0FBQztRQUNILE9BQU8sS0FBSyxDQUFDLGNBQWMsQ0FBQyxHQUFHLFFBQVEsQ0FBQyxXQUFXLFFBQVEsUUFBUSxDQUFDLE1BQU0sRUFBRSxDQUFDLENBQUE7SUFDL0UsQ0FBQztJQUFDLE1BQU0sQ0FBQztRQUNQLE1BQU0sSUFBSSxLQUFLLENBQ2IsR0FBRyxRQUFRLENBQUMsV0FBVyxnQ0FBZ0MsWUFBWSxXQUFXO1lBQzVFLHFEQUFxRCxHQUFHLGVBQWUsQ0FDMUUsQ0FBQTtJQUNILENBQUM7QUFDSCxDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiaW1wb3J0IHsgQklOQVJZX0VOViwgUEFDS0FHRV9OQU1FLCBQTEFURk9STVMgfSBmcm9tIFwiLi4vLi4vc2V0dGluZ3MudHNcIlxuXG4vKiogRmluZCB0aGUgaHRtbHByZXNzIGJpbmFyeTogdGhlIGVudiBvdmVycmlkZSBmaXJzdCwgZWxzZSB0aGUgbWF0Y2hpbmcgcGxhdGZvcm0gcGFja2FnZS4gKi9cbmV4cG9ydCBmdW5jdGlvbiByZXNvbHZlQmluYXJ5KHByb3BzOiB7XG4gIHBsYXRmb3JtOiBzdHJpbmdcbiAgYXJjaDogc3RyaW5nXG4gIGVudjogUmVjb3JkPHN0cmluZywgc3RyaW5nIHwgdW5kZWZpbmVkPlxuICByZXNvbHZlUGFja2FnZTogKHNwZWNpZmllcjogc3RyaW5nKSA9PiBzdHJpbmdcbn0pIHtcbiAgY29uc3Qgb3ZlcnJpZGUgPSBwcm9wcy5lbnZbQklOQVJZX0VOVl1cbiAgaWYgKG92ZXJyaWRlKSByZXR1cm4gb3ZlcnJpZGVcblxuICBjb25zdCBrZXkgPSBgJHtwcm9wcy5wbGF0Zm9ybX0tJHtwcm9wcy5hcmNofWBcbiAgY29uc3QgcGxhdGZvcm0gPSBQTEFURk9STVNba2V5XVxuICBpZiAoIXBsYXRmb3JtKSB7XG4gICAgY29uc3Qgc3VwcG9ydGVkID0gT2JqZWN0LmtleXMoUExBVEZPUk1TKS5qb2luKFwiLCBcIilcbiAgICB0aHJvdyBuZXcgRXJyb3IoXG4gICAgICBgJHtQQUNLQUdFX05BTUV9IGhhcyBubyBiaW5hcnkgZm9yICR7a2V5fTsgc3VwcG9ydGVkOiAke3N1cHBvcnRlZH0uIGAgK1xuICAgICAgICBgU2V0ICR7QklOQVJZX0VOVn0gdG8gYSBiaW5hcnkgYnVpbHQgd2l0aCBjYXJnbyB0byBydW4gaXQgYW55d2F5LmAsXG4gICAgKVxuICB9XG4gIHRyeSB7XG4gICAgcmV0dXJuIHByb3BzLnJlc29sdmVQYWNrYWdlKGAke3BsYXRmb3JtLnBhY2thZ2VOYW1lfS9iaW4vJHtwbGF0Zm9ybS5iaW5hcnl9YClcbiAgfSBjYXRjaCB7XG4gICAgdGhyb3cgbmV3IEVycm9yKFxuICAgICAgYCR7cGxhdGZvcm0ucGFja2FnZU5hbWV9IGlzIG5vdCBpbnN0YWxsZWQuIFJlaW5zdGFsbCAke1BBQ0tBR0VfTkFNRX0gd2l0aG91dCBgICtcbiAgICAgICAgYC0tbm8tb3B0aW9uYWwgLyAtLW9taXQ9b3B0aW9uYWwgc28gdGhlIGJpbmFyeSBmb3IgJHtrZXl9IGNvbWVzIGFsb25nLmAsXG4gICAgKVxuICB9XG59XG4iXX0=

package/build/entrypoints/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/build/entrypoints/main.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { resolveBinary } from "../actions/binary/resolve.js";
+const require = createRequire(import.meta.url);
+let binary;
+try {
+    binary = resolveBinary({
+        platform: process.platform,
+        arch: process.arch,
+        env: process.env,
+        resolvePackage: specifier => require.resolve(specifier),
+    });
+}
+catch (error) {
+    console.error(`error: ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(1);
+}
+const result = spawnSync(binary, process.argv.slice(2), { stdio: "inherit" });
+if (result.error) {
+    console.error(`error: cannot run ${binary}: ${result.error.message}`);
+    process.exit(1);
+}
+// Re-raise a signal so a parent sees the same death the binary had (Ctrl-C under start)
+if (result.signal)
+    process.kill(process.pid, result.signal);
+process.exit(result.status ?? 1);
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibWFpbi5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL2VudHJ5cG9pbnRzL21haW4udHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IjtBQUNBLE9BQU8sRUFBRSxTQUFTLEVBQUUsTUFBTSxvQkFBb0IsQ0FBQTtBQUM5QyxPQUFPLEVBQUUsYUFBYSxFQUFFLE1BQU0sYUFBYSxDQUFBO0FBQzNDLE9BQU8sRUFBRSxhQUFhLEVBQUUsTUFBTSw4QkFBOEIsQ0FBQTtBQUU1RCxNQUFNLE9BQU8sR0FBRyxhQUFhLENBQUMsT0FBTyxJQUFJLENBQUMsR0FBRyxDQUFDLENBQUE7QUFFOUMsSUFBSSxNQUFjLENBQUE7QUFDbEIsSUFBSSxDQUFDO0lBQ0gsTUFBTSxHQUFHLGFBQWEsQ0FBQztRQUNyQixRQUFRLEVBQUUsT0FBTyxDQUFDLFFBQVE7UUFDMUIsSUFBSSxFQUFFLE9BQU8sQ0FBQyxJQUFJO1FBQ2xCLEdBQUcsRUFBRSxPQUFPLENBQUMsR0FBRztRQUNoQixjQUFjLEVBQUUsU0FBUyxDQUFDLEVBQUUsQ0FBQyxPQUFPLENBQUMsT0FBTyxDQUFDLFNBQVMsQ0FBQztLQUN4RCxDQUFDLENBQUE7QUFDSixDQUFDO0FBQUMsT0FBTyxLQUFLLEVBQUUsQ0FBQztJQUNmLE9BQU8sQ0FBQyxLQUFLLENBQUMsVUFBVSxLQUFLLFlBQVksS0FBSyxDQUFDLENBQUMsQ0FBQyxLQUFLLENBQUMsT0FBTyxDQUFDLENBQUMsQ0FBQyxNQUFNLENBQUMsS0FBSyxDQUFDLEVBQUUsQ0FBQyxDQUFBO0lBQ2pGLE9BQU8sQ0FBQyxJQUFJLENBQUMsQ0FBQyxDQUFDLENBQUE7QUFDakIsQ0FBQztBQUVELE1BQU0sTUFBTSxHQUFHLFNBQVMsQ0FBQyxNQUFNLEVBQUUsT0FBTyxDQUFDLElBQUksQ0FBQyxLQUFLLENBQUMsQ0FBQyxDQUFDLEVBQUUsRUFBRSxLQUFLLEVBQUUsU0FBUyxFQUFFLENBQUMsQ0FBQTtBQUM3RSxJQUFJLE1BQU0sQ0FBQyxLQUFLLEVBQUUsQ0FBQztJQUNqQixPQUFPLENBQUMsS0FBSyxDQUFDLHFCQUFxQixNQUFNLEtBQUssTUFBTSxDQUFDLEtBQUssQ0FBQyxPQUFPLEVBQUUsQ0FBQyxDQUFBO0lBQ3JFLE9BQU8sQ0FBQyxJQUFJLENBQUMsQ0FBQyxDQUFDLENBQUE7QUFDakIsQ0FBQztBQUNELHdGQUF3RjtBQUN4RixJQUFJLE1BQU0sQ0FBQyxNQUFNO0lBQUUsT0FBTyxDQUFDLElBQUksQ0FBQyxPQUFPLENBQUMsR0FBRyxFQUFFLE1BQU0sQ0FBQyxNQUFNLENBQUMsQ0FBQTtBQUMzRCxPQUFPLENBQUMsSUFBSSxDQUFDLE1BQU0sQ0FBQyxNQUFNLElBQUksQ0FBQyxDQUFDLENBQUEiLCJzb3VyY2VzQ29udGVudCI6WyIjIS91c3IvYmluL2VudiBub2RlXG5pbXBvcnQgeyBzcGF3blN5bmMgfSBmcm9tIFwibm9kZTpjaGlsZF9wcm9jZXNzXCJcbmltcG9ydCB7IGNyZWF0ZVJlcXVpcmUgfSBmcm9tIFwibm9kZTptb2R1bGVcIlxuaW1wb3J0IHsgcmVzb2x2ZUJpbmFyeSB9IGZyb20gXCIuLi9hY3Rpb25zL2JpbmFyeS9yZXNvbHZlLnRzXCJcblxuY29uc3QgcmVxdWlyZSA9IGNyZWF0ZVJlcXVpcmUoaW1wb3J0Lm1ldGEudXJsKVxuXG5sZXQgYmluYXJ5OiBzdHJpbmdcbnRyeSB7XG4gIGJpbmFyeSA9IHJlc29sdmVCaW5hcnkoe1xuICAgIHBsYXRmb3JtOiBwcm9jZXNzLnBsYXRmb3JtLFxuICAgIGFyY2g6IHByb2Nlc3MuYXJjaCxcbiAgICBlbnY6IHByb2Nlc3MuZW52LFxuICAgIHJlc29sdmVQYWNrYWdlOiBzcGVjaWZpZXIgPT4gcmVxdWlyZS5yZXNvbHZlKHNwZWNpZmllciksXG4gIH0pXG59IGNhdGNoIChlcnJvcikge1xuICBjb25zb2xlLmVycm9yKGBlcnJvcjogJHtlcnJvciBpbnN0YW5jZW9mIEVycm9yID8gZXJyb3IubWVzc2FnZSA6IFN0cmluZyhlcnJvcil9YClcbiAgcHJvY2Vzcy5leGl0KDEpXG59XG5cbmNvbnN0IHJlc3VsdCA9IHNwYXduU3luYyhiaW5hcnksIHByb2Nlc3MuYXJndi5zbGljZSgyKSwgeyBzdGRpbzogXCJpbmhlcml0XCIgfSlcbmlmIChyZXN1bHQuZXJyb3IpIHtcbiAgY29uc29sZS5lcnJvcihgZXJyb3I6IGNhbm5vdCBydW4gJHtiaW5hcnl9OiAke3Jlc3VsdC5lcnJvci5tZXNzYWdlfWApXG4gIHByb2Nlc3MuZXhpdCgxKVxufVxuLy8gUmUtcmFpc2UgYSBzaWduYWwgc28gYSBwYXJlbnQgc2VlcyB0aGUgc2FtZSBkZWF0aCB0aGUgYmluYXJ5IGhhZCAoQ3RybC1DIHVuZGVyIHN0YXJ0KVxuaWYgKHJlc3VsdC5zaWduYWwpIHByb2Nlc3Mua2lsbChwcm9jZXNzLnBpZCwgcmVzdWx0LnNpZ25hbClcbnByb2Nlc3MuZXhpdChyZXN1bHQuc3RhdHVzID8/IDEpXG4iXX0=

package/build/settings.d.ts

@@ -0,0 +1,14 @@
+export interface Platform {
+    /** The npm package that carries this platform's binary. */
+    packageName: string;
+    /** The Rust target the binary is compiled for. */
+    target: string;
+    /** The binary's file name inside the package's `bin/`. */
+    binary: string;
+}
+/** The npm package users install; it pulls in the one platform package that matches. */
+export declare const PACKAGE_NAME = "gethtmlpress";
+/** An environment variable that points at a binary to run instead of the installed one. */
+export declare const BINARY_ENV = "HTMLPRESS_BINARY";
+/** Every published platform, keyed by `${process.platform}-${process.arch}`. */
+export declare const PLATFORMS: Record<string, Platform>;

package/build/settings.js

@@ -0,0 +1,18 @@
+/** The npm package users install; it pulls in the one platform package that matches. */
+export const PACKAGE_NAME = "gethtmlpress";
+/** An environment variable that points at a binary to run instead of the installed one. */
+export const BINARY_ENV = "HTMLPRESS_BINARY";
+/** Every published platform, keyed by `${process.platform}-${process.arch}`. */
+export const PLATFORMS = {
+    "linux-x64": createPlatform("linux-x64", "x86_64-unknown-linux-musl"),
+    "linux-arm64": createPlatform("linux-arm64", "aarch64-unknown-linux-musl"),
+    "darwin-x64": createPlatform("darwin-x64", "x86_64-apple-darwin"),
+    "darwin-arm64": createPlatform("darwin-arm64", "aarch64-apple-darwin"),
+    "win32-x64": createPlatform("win32-x64", "x86_64-pc-windows-msvc"),
+    "win32-arm64": createPlatform("win32-arm64", "aarch64-pc-windows-msvc"),
+};
+function createPlatform(key, target) {
+    const binary = key.startsWith("win32") ? "htmlpress.exe" : "htmlpress";
+    return { packageName: `@htmlpress/${key}`, target, binary };
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic2V0dGluZ3MuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zZXR0aW5ncy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFTQSx3RkFBd0Y7QUFDeEYsTUFBTSxDQUFDLE1BQU0sWUFBWSxHQUFHLGNBQWMsQ0FBQTtBQUUxQywyRkFBMkY7QUFDM0YsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHLGtCQUFrQixDQUFBO0FBRTVDLGdGQUFnRjtBQUNoRixNQUFNLENBQUMsTUFBTSxTQUFTLEdBQTZCO0lBQ2pELFdBQVcsRUFBRSxjQUFjLENBQUMsV0FBVyxFQUFFLDJCQUEyQixDQUFDO0lBQ3JFLGFBQWEsRUFBRSxjQUFjLENBQUMsYUFBYSxFQUFFLDRCQUE0QixDQUFDO0lBQzFFLFlBQVksRUFBRSxjQUFjLENBQUMsWUFBWSxFQUFFLHFCQUFxQixDQUFDO0lBQ2pFLGNBQWMsRUFBRSxjQUFjLENBQUMsY0FBYyxFQUFFLHNCQUFzQixDQUFDO0lBQ3RFLFdBQVcsRUFBRSxjQUFjLENBQUMsV0FBVyxFQUFFLHdCQUF3QixDQUFDO0lBQ2xFLGFBQWEsRUFBRSxjQUFjLENBQUMsYUFBYSxFQUFFLHlCQUF5QixDQUFDO0NBQ3hFLENBQUE7QUFFRCxTQUFTLGNBQWMsQ0FBQyxHQUFXLEVBQUUsTUFBYztJQUNqRCxNQUFNLE1BQU0sR0FBRyxHQUFHLENBQUMsVUFBVSxDQUFDLE9BQU8sQ0FBQyxDQUFDLENBQUMsQ0FBQyxlQUFlLENBQUMsQ0FBQyxDQUFDLFdBQVcsQ0FBQTtJQUN0RSxPQUFPLEVBQUUsV0FBVyxFQUFFLGNBQWMsR0FBRyxFQUFFLEVBQUUsTUFBTSxFQUFFLE1BQU0sRUFBRSxDQUFBO0FBQzdELENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyJleHBvcnQgaW50ZXJmYWNlIFBsYXRmb3JtIHtcbiAgLyoqIFRoZSBucG0gcGFja2FnZSB0aGF0IGNhcnJpZXMgdGhpcyBwbGF0Zm9ybSdzIGJpbmFyeS4gKi9cbiAgcGFja2FnZU5hbWU6IHN0cmluZ1xuICAvKiogVGhlIFJ1c3QgdGFyZ2V0IHRoZSBiaW5hcnkgaXMgY29tcGlsZWQgZm9yLiAqL1xuICB0YXJnZXQ6IHN0cmluZ1xuICAvKiogVGhlIGJpbmFyeSdzIGZpbGUgbmFtZSBpbnNpZGUgdGhlIHBhY2thZ2UncyBgYmluL2AuICovXG4gIGJpbmFyeTogc3RyaW5nXG59XG5cbi8qKiBUaGUgbnBtIHBhY2thZ2UgdXNlcnMgaW5zdGFsbDsgaXQgcHVsbHMgaW4gdGhlIG9uZSBwbGF0Zm9ybSBwYWNrYWdlIHRoYXQgbWF0Y2hlcy4gKi9cbmV4cG9ydCBjb25zdCBQQUNLQUdFX05BTUUgPSBcImdldGh0bWxwcmVzc1wiXG5cbi8qKiBBbiBlbnZpcm9ubWVudCB2YXJpYWJsZSB0aGF0IHBvaW50cyBhdCBhIGJpbmFyeSB0byBydW4gaW5zdGVhZCBvZiB0aGUgaW5zdGFsbGVkIG9uZS4gKi9cbmV4cG9ydCBjb25zdCBCSU5BUllfRU5WID0gXCJIVE1MUFJFU1NfQklOQVJZXCJcblxuLyoqIEV2ZXJ5IHB1Ymxpc2hlZCBwbGF0Zm9ybSwga2V5ZWQgYnkgYCR7cHJvY2Vzcy5wbGF0Zm9ybX0tJHtwcm9jZXNzLmFyY2h9YC4gKi9cbmV4cG9ydCBjb25zdCBQTEFURk9STVM6IFJlY29yZDxzdHJpbmcsIFBsYXRmb3JtPiA9IHtcbiAgXCJsaW51eC14NjRcIjogY3JlYXRlUGxhdGZvcm0oXCJsaW51eC14NjRcIiwgXCJ4ODZfNjQtdW5rbm93bi1saW51eC1tdXNsXCIpLFxuICBcImxpbnV4LWFybTY0XCI6IGNyZWF0ZVBsYXRmb3JtKFwibGludXgtYXJtNjRcIiwgXCJhYXJjaDY0LXVua25vd24tbGludXgtbXVzbFwiKSxcbiAgXCJkYXJ3aW4teDY0XCI6IGNyZWF0ZVBsYXRmb3JtKFwiZGFyd2luLXg2NFwiLCBcIng4Nl82NC1hcHBsZS1kYXJ3aW5cIiksXG4gIFwiZGFyd2luLWFybTY0XCI6IGNyZWF0ZVBsYXRmb3JtKFwiZGFyd2luLWFybTY0XCIsIFwiYWFyY2g2NC1hcHBsZS1kYXJ3aW5cIiksXG4gIFwid2luMzIteDY0XCI6IGNyZWF0ZVBsYXRmb3JtKFwid2luMzIteDY0XCIsIFwieDg2XzY0LXBjLXdpbmRvd3MtbXN2Y1wiKSxcbiAgXCJ3aW4zMi1hcm02NFwiOiBjcmVhdGVQbGF0Zm9ybShcIndpbjMyLWFybTY0XCIsIFwiYWFyY2g2NC1wYy13aW5kb3dzLW1zdmNcIiksXG59XG5cbmZ1bmN0aW9uIGNyZWF0ZVBsYXRmb3JtKGtleTogc3RyaW5nLCB0YXJnZXQ6IHN0cmluZyk6IFBsYXRmb3JtIHtcbiAgY29uc3QgYmluYXJ5ID0ga2V5LnN0YXJ0c1dpdGgoXCJ3aW4zMlwiKSA/IFwiaHRtbHByZXNzLmV4ZVwiIDogXCJodG1scHJlc3NcIlxuICByZXR1cm4geyBwYWNrYWdlTmFtZTogYEBodG1scHJlc3MvJHtrZXl9YCwgdGFyZ2V0LCBiaW5hcnkgfVxufVxuIl19

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "gethtmlpress",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Turn a folder of HTML pages into a site: one layout, one theme, live reload, made for agents",
+  "keywords": [
+    "agents",
+    "html",
+    "htmlpress",
+    "llm",
+    "static-site"
+  ],
+  "homepage": "https://htmlpress.dev",
+  "license": "MIT",
+  "author": "Evgeny Karev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/datisthq/htmlpress.git",
+    "directory": "typescript"
+  },
+  "bin": {
+    "htmlpress": "./build/entrypoints/main.js"
+  },
+  "files": [
+    "build",
+    "skills"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "optionalDependencies": {
+    "@htmlpress/linux-x64": "0.1.0",
+    "@htmlpress/linux-arm64": "0.1.0",
+    "@htmlpress/darwin-x64": "0.1.0",
+    "@htmlpress/darwin-arm64": "0.1.0",
+    "@htmlpress/win32-x64": "0.1.0",
+    "@htmlpress/win32-arm64": "0.1.0"
+  }
+}

package/skills/htmlpress-authoring/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: htmlpress-authoring
+description: Use when writing or editing pages in an htmlpress project — the page contract (title, order, head, metas), headings and the TOC, semantic HTML, the htmlpress-* components, code blocks, math, includes and checking the build.
+---
+
+# Htmlpress Authoring
+
+An htmlpress project is a folder of `.html` pages. Htmlpress wraps each in one layout with a
+navigation and a theme, so a page carries content only: no `<nav>`, no site header, no styling.
+
+## When to use this skill
+
+Invoke when the user asks to:
+
+- Add, edit, move or reorder pages, or group them in the navigation.
+- Use a callout, tabs, cards, steps or another component, or a code block, formula or diagram.
+- Pull a shared partial or a source file into a page.
+
+The config keys are in `htmlpress-configuration`; a different look in `htmlpress-customization`.
+
+## A page
+
+```html
+<title>Getting started</title>
+<meta name="description" content="Install and run it in a minute." />
+<meta name="order" content="1" />
+
+<h1>Getting started</h1>
+<p>Plain semantic HTML.</p>
+```
+
+- A full document (`<!doctype html>…<body>`) and a bare fragment are read the same way.
+- `<title>` names the page in the navigation and the tab; without it the first `<h1>`, then the
+  file name. Give every page one `<title>` and one `<h1>`.
+- `<meta name="order" content="N">` (an integer) sorts the navigation, lower first.
+  `index.html` always comes first; unordered pages follow by path, then negative orders
+  (`-1` pins a page last).
+- Other `<head>` tags (`<link>`, `<style>`, `<script>`) are kept and added after the theme.
+- The navigation nests pages by folder at any depth (`guides/cli/…` inside `guides/…`), each
+  group named by its `index.html`, whose title links to it.
+- Pages are written to the same path, so link between them with relative hrefs
+  (`guides/build.html`). Images and other files are copied as-is; a relative `src`,
+  `srcset` or `poster` resolves from the source file, even when the page moves.
+- A root `404.html` is the not-found page, kept out of the navigation; without one a built-in
+  is used.
+
+## Page metas
+
+| Meta                                         | Effect                                                       |
+| -------------------------------------------- | ------------------------------------------------------------ |
+| `description`                                | the page's summary for search, previews and `llms.txt`       |
+| `image`                                      | its social preview image, relative to the file; needs `site` |
+| `date` (`YYYY-MM-DD`), `author` (repeatable) | dates and signs it (a byline; none with `layout`)            |
+| `keywords` (`a, b`)                          | tags it (a blog post's tag pages)                            |
+| `label`                                      | a short name in the navigation                               |
+| `icon`                                       | a Lucide icon; top-level entries and folder index pages      |
+| `path` (`/start/`)                           | serves the page at another URL                               |
+| `sidebar` (`false`)                          | built, not listed                                            |
+| `toc` (`false`)                              | no table of contents                                         |
+| `layout` (`<name>`)                          | another layout, from `htmlpress-customization`               |
+| `language` (`<code>`)                        | marks the page a translation                                 |
+| `source-url`, `source-action` (`view`)       | the page's source link                                       |
+
+A file that cannot carry metas, such as a `README.md`, gets them from `patches` in the config.
+
+## Translations
+
+With `languages` in the config, a translation is `page.<code>.html` beside `page.html`, or a
+file with `<meta name="language" content="<code>">`. It pairs with the original by URL below the
+language prefix, so a renamed one needs the same `<meta name="path">`. Untranslated pages stay
+listed in every language with a badge and link to the original.
+
+## Headings
+
+- `<h2>` to `<h4>` outside components make the page's table of contents; any `<h2>` to `<h6>`
+  without an `id` gets a slug of its text and an anchor link. Give a heading an `id` only when a link needs it fixed.
+- A heading takes `data-toc="false"` (shown, not in the TOC) or `data-toc="only"` (in the TOC,
+  not shown); `<htmlpress-toc level="2">` (2–4, default 3) in a page renders its TOC inline.
+
+## Semantic HTML first
+
+The theme styles the elements themselves: headings, `<p>`, lists, `<table>`, `<pre><code>`,
+`<blockquote>`, `<details>`/`<summary>`, `<figure>`/`<figcaption>`, `<dl>`, `<kbd>`, `<hr>`.
+
+- No inline `style`, no classes for looks, no utility CSS: every page should look like the same
+  site. A site-wide change is a token (`htmlpress-customization`).
+- An image with `data-theme="light"` or `"dark"` shows in that theme only.
+- `<abbr title>` and footnote references (`<sup><a href="#n1">` to an `<li id="n1">`) show a
+  hover hint; headings get a link on their own.
+- Bare URLs and emails in prose become links and GitHub shortcodes (`:rocket:`) become emoji at
+  build time; text in links, code and `data-literal` elements stays as written.
+- LaTeX: `$E = mc^2$` inline and `$$…$$` as a block (pandoc's rule keeps `$5 and $10` text; `\$`
+  is a dollar), or `<htmlpress-math display>…</htmlpress-math>`; rendered to MathML at build
+  time, and invalid LaTeX fails the build.
+- `<htmlpress-include src="partial.html">` pastes in another file by path, relative to the page:
+  an `.html` body, rendered `.md`, or any other file as a titled code block that takes
+  `data-lines` and the other code block attributes. Exclude the partials folder in the config.
+
+## Code blocks
+
+- Escape code inside `<pre><code>`: `&lt;` and `&amp;`. Name its language,
+  `<pre><code class="language-rust">`, to highlight it at build time; an inline
+  `<code class="language-js">` is highlighted too.
+- `data-lines="2,4-5"` marks lines, `data-line-numbers` numbers them, `data-add`/`data-remove`
+  show a diff, `data-focus` dims the other lines, `data-error`/`data-warning` flag lines and
+  `data-words="a,b"` marks words.
+- `<pre data-title="file.yaml">` adds a title bar with the language's logo;
+  `<pre data-collapse="10">` shows 10 lines with an Expand bar.
+- `<pre><code class="language-ansi">` renders terminal color escapes (raw or `&#27;[31m`).
+- Every block gets copy and wrap buttons. Tabs holding only code blocks join into one framed block.
+
+## Components
+
+Only these; anything else is plain HTML. Put block content (`<p>`, `<h3>`, `<pre>`) inside a
+component, not bare text.
+
+| Element                                          | Use                                                                                                                     |
+| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
+| `<htmlpress-callout type="…" label="…">`         | a note; `type` is `info` (default), `note`, `tip`, `success`, `warning`, `danger`                                       |
+| `<htmlpress-grid cols="2">` + `<htmlpress-card>` | cards in columns (`cols` 2–4, else responsive); `<h3><a>` links a card                                                  |
+| `<htmlpress-tabs sync="…">` + `<section title>`  | tabs, one per `<section>`; tabs sharing `sync` switch together                                                          |
+| `<htmlpress-steps>` + `<ol>`                     | numbered steps, one per `<li>`, each led by an `<h3>`                                                                   |
+| `<htmlpress-badge type="…">`                     | an inline label; `type` as a callout's, `neutral`, `outline`, `ghost` or `link`                                         |
+| `<htmlpress-file-tree>` + nested `<ul>`          | a file tree; an `<li>` holding a `<ul>` is a folder                                                                     |
+| `<htmlpress-table>` + `<table>`                  | a table sorted by a click on a `<thead>` header                                                                         |
+| `<htmlpress-zoom>` + `<img>`                     | an image that opens full screen on click                                                                                |
+| `<htmlpress-icon name="…">`                      | an inline Lucide icon; names at htmlpress.dev/authoring/rich-elements.html#icons                                        |
+| `<htmlpress-button type="…">` + `<a>`            | a call-to-action link; `type` `secondary`/`outline`/`ghost`/`link`/`positive`/`warning`/`destructive`, `size` `sm`/`lg` |
+| `<htmlpress-package-tabs>` + `<pre><code>`       | one `npm`/`npx` command, built into npm, pnpm, yarn and bun tabs                                                        |
+| `<htmlpress-terminal title="…">` + `<pre>`       | terminal output: `<kbd>` command, `<samp>` output, `<ins>`/`<del>`/`<mark>` colours                                     |
+| `<htmlpress-youtube>` + `<a href>`               | a YouTube video player for the linked video                                                                             |
+| `<htmlpress-soundcloud>` + `<a href>`            | a SoundCloud player for the linked track                                                                                |
+| `<htmlpress-mermaid>` + `<pre>`                  | a Mermaid diagram from the source in `<pre>` (escape `<` and `&`)                                                       |
+
+## Verification
+
+```sh
+htmlpress build <root> --json   # {"output": "...", "pages": N, "files": N}; errors on stderr
+htmlpress start <root>          # http://localhost:8000 (or the next free port to 8009); --host for the network
+htmlpress --llms                # every command's input and output schema
+```
+
+After editing, run `build --json` and confirm `pages` counts every page and the exit code is 0.
+For a visual check, run `start` and open the page; look at it narrow as well as wide. Never edit
+`.htmlpress/build/`: every build replaces it.
+
+## References
+
+- Pages: https://htmlpress.dev/authoring/
+- Components: https://htmlpress.dev/authoring/rich-elements.html
+- Code blocks: https://htmlpress.dev/authoring/code-blocks.html

package/skills/htmlpress-configuration/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: htmlpress-configuration
+description: Use when editing htmlpress.yaml — site metadata, base, include/exclude globs, code themes, sections (blog, changelog, custom), links, languages, versions, patches, head tags, agent skills, content signals and the edit link.
+---
+
+# Htmlpress Configuration
+
+`htmlpress.yaml` at the project root is optional; its keys follow Livemark's config. An unknown
+key is an error, so a typo fails the build instead of being ignored.
+
+## When to use this skill
+
+Invoke when the user asks to:
+
+- Set the site's title, description, logo, favicon, banner or URL.
+- Choose which files become pages, or leave some out.
+- Add a blog, a changelog or another section, or links in the header or sidebar.
+- Publish the site in several languages, or keep docs for older versions.
+- Give a file metas it cannot carry, or publish a Markdown file as a page.
+- Add tags to every page's `<head>`, publish skills or set `robots.txt` signals.
+
+## The config shape
+
+```yaml
+site: https://example.com
+base: /
+title: Acme
+description: Acme's docs.
+logo: /logo.svg
+favicon: /favicon.svg
+banner: <a href="/blog/">We shipped 2.0</a>
+include: [docs/**/*.html]
+exclude: [docs/includes/**]
+codeThemeLight: catppuccin-latte
+codeThemeDark: catppuccin-mocha
+edit: https://github.com/acme/acme/edit/main/
+links:
+  - { title: GitHub, url: https://github.com/acme/acme, position: header, icon: github }
+sections:
+  - { title: Blog, prefix: /blog/, type: blog }
+patches:
+  - { file: README.md, article: { title: Overview, order: 1 } }
+skills: [.skills/*/SKILL.md]
+contentSignals: { search: true, aiInput: true, aiTrain: false }
+head:
+  meta: [{ name: theme-color, content: "#0b5" }]
+```
+
+- `site` — the canonical origin; with it a build writes `sitemap.xml` and absolute feed URLs.
+- `base` — a sub-path such as `/repo/`. Root-relative URLs get it as a prefix, so write them
+  without it.
+- `title`, `description`, `logo`, `favicon` (URLs) and `banner` (HTML above the header).
+- `include` — globs of the `.html` files that become pages, default `**/*.html`. Only files under
+  a glob's base, its folders before the first wildcard, are read, and they are served without it:
+  `docs/**/*.html` serves `docs/guide.html` at `/guide.html`. Other files there are copied as-is.
+- `exclude` — globs left out of the build: partials for includes, drafts.
+- `codeThemeLight`, `codeThemeDark` — the code block themes, by Shiki theme name.
+- `edit` — a URL prefix for an "Edit on GitHub" link.
+
+## Sections
+
+Each has a `title` and a `prefix`; optional `icon`, `position`, `siteTitle`, `siteLink` and
+`siteDescription`. The sidebar and pager then show only the open section's pages.
+
+- `type: article` (the default) — the pages under the prefix.
+- `type: blog` — dated posts (`date`, `author`, `keywords` metas) with tag pages and RSS.
+- `type: changelog` plus `source` — a page per version of a Markdown changelog, or per
+  release of a GitHub repository URL (`GITHUB_TOKEN` when set, cached in `.htmlpress/cache/`); `version: true`
+  shows the latest version beside the title.
+- `type: custom` plus `url` — a link to anywhere.
+
+## Links
+
+Each has `title`, `url` and `position: header | sidebar`; optional `icon` and `prefix`, which
+shows the link only under one folder.
+
+## Languages
+
+`languages` lists each `code` and `label`, optional `locale`, `dir` (`ltr` or `rtl`), `flag` and
+`messages` replacing UI strings. The first is the default; the others are served under
+`/<code>/`. With `languages`, `title`, `description`, `banner` and link and section titles also
+take a map by language code (`title: { en: Docs, es: Documentos }`). Translated pages are in
+`htmlpress-authoring`.
+
+## Versions
+
+There is no dedicated option. For a few versions on one branch, put each older version's pages
+in a folder with a section of its own (`title: v1`, `prefix: /v1/`, `siteTitle: Acme v1`);
+search stays site-wide, so results mix versions. For majors on their own branches, deploy each
+branch as its own site (`base`, a `banner` linking to the latest) and link them with a `custom`
+section.
+
+## Patches
+
+Each patch is a `file` and an `article` of metas (`title`, `label`, `description`, `icon`,
+`order`, `path`, `sidebar`, `toc`, `image`, `author`, `date`, `tags`, `sourceUrl`,
+`sourceAction`), set without touching the file; a patched `.md` file such as `README.md` is
+published as a page. A patched path outside the project, through a symlink or into a dot-folder is refused.
+
+## Agents and head
+
+- `skills` — globs of `SKILL.md` files to publish under `.well-known/agent-skills/`.
+- `contentSignals` — `search`, `aiInput`, `aiTrain` for `robots.txt`.
+- `head` — `meta`, `links`, `scripts`: lists of attribute maps added to every page; a script's
+  `children` is its source.
+
+## Rules of thumb
+
+- Change one key at a time and rebuild: the error names the key.
+- Keep the config for site-wide facts; a page's own facts are its metas (`htmlpress-authoring`).
+- `htmlpress start` rebuilds on a config change; no restart needed.
+
+## Verification
+
+Run `htmlpress build <root> --json`: exit code 0 and the expected `pages` count. An unknown or
+misspelt key fails here with its name.
+
+## References
+
+- Configuration: https://htmlpress.dev/customization/configuration-file.html
+- Sections: https://htmlpress.dev/customization/article-sections.html
+- Translations: https://htmlpress.dev/customization/translations.html
+- Versioning: https://htmlpress.dev/customization/versioning.html
+- Patches: https://htmlpress.dev/customization/article-patches.html

package/skills/htmlpress-customization/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: htmlpress-customization
+description: Use when changing an htmlpress site's look or chrome — overriding --htmlpress-* tokens, escaping the layout, styles or a component into .htmlpress/ with `htmlpress escape`, adding layouts and project components.
+---
+
+# Htmlpress Customization
+
+Htmlpress ships a layout, a theme and a library of components, all compiled into the binary.
+A file under `.htmlpress/` at a built-in's path replaces it; a new name adds one of your own.
+
+## When to use this skill
+
+Invoke when the user asks to:
+
+- Rebrand: colours, fonts, widths, radius.
+- Change the header, sidebar, footer or another part of the chrome.
+- Restyle a component, or add a block the built-in components do not have.
+- Give some pages a different layout, such as a landing page without the sidebar
+  (`htmlpress-landing` covers what goes on one).
+
+Do not escape for content: a page's own needs are semantic HTML and components
+(`htmlpress-authoring`).
+
+## Tokens first
+
+Most looks are a token. Override it in `.htmlpress/styles/tokens.css`, or in one page's own
+`<style>` for that page only:
+
+```css
+:root {
+  --htmlpress-accent: oklch(0.55 0.24 27);
+}
+```
+
+`--htmlpress-accent`, `-accent-text`, `-font`, `-mono`, `-bg`, `-surface`, `-text`, `-muted`,
+`-prose`, `-prose-strong`, `-prose-marker`, `-border`, `-shadow`, `-radius`, `-width`,
+`-nav-width`, `-banner`, `-banner-text`, `-highlight`, `-highlight-text` (search matches on
+the page a result opened), and the
+callout and badge tones `-info`, `-success`, `-warning`, `-danger`.
+
+## Escaping
+
+```sh
+htmlpress escape                         # list every file, marking the escaped ones
+htmlpress escape htmlpress-tabs          # a component's .css and .js
+htmlpress escape layout.html styles/tokens.css
+htmlpress escape htmlpress-tabs -r docs  # in another project folder
+```
+
+`escape` copies a default to start from and never overwrites a file you already have. Deleting
+an escape restores the default. An escaped copy keeps the code it was copied from, so after an
+upgrade it misses the new defaults: escape only what you change.
+
+| Path under `.htmlpress/`                         | Replaces                                                          |
+| ------------------------------------------------ | ----------------------------------------------------------------- |
+| `layout.html`                                    | the page around the content                                       |
+| `layouts/<name>.html`                            | a layout of your own, picked by `<meta name="layout">`            |
+| `styles/tokens.css`, `layout.css`, `content.css` | the global theme: tokens, page globals, content elements          |
+| `favicon.svg`                                    | the icon linked when the config sets neither `favicon` nor `logo` |
+| `components/<name>/<name>.css`, `.js`            | one component, `<htmlpress-<name>>` without its prefix            |
+
+## Layouts
+
+`layout.html` is plain HTML: htmlpress fills its `<head>` and replaces `<htmlpress-content>`,
+`<htmlpress-brand>`, `<htmlpress-banner>`, `<htmlpress-nav>`, `<htmlpress-links>`,
+`<htmlpress-breadcrumbs>`, `<htmlpress-toc>`, `<htmlpress-pager>`, `<htmlpress-edit>`,
+`<htmlpress-toolbar>`, `<htmlpress-footer>`, `<htmlpress-language>` (the language picker) and
+`<htmlpress-skip>` at build time, every string in the page's language. The interactive ones,
+`<htmlpress-nav-toggle>`, `<htmlpress-search>`, `<htmlpress-theme-toggle>`, `<htmlpress-toc-bar>`
+(the phone's contents bar and sheet) and `<htmlpress-back-to-top>`, run in the browser; the first three get their button at build time,
+so the header is whole on its first frame. A head script sets `data-scripted` on `<html>`:
+without it those buttons stay hidden, so style anything that needs scripts under
+`:root[data-scripted]`. An element with nothing to show is removed.
+
+Pages crossfade only their content: `<htmlpress-header>` and `<htmlpress-sidebar>` carry the
+view transition names `htmlpress-header` and `htmlpress-sidebar`, and a hovered link's page is
+prerendered. An escape of either component's `.css` keeps its `view-transition-name`, or it
+crossfades with the content.
+
+The frame is elements too, never classes: `<htmlpress-shell>`, `-sidebar`, `-main`, `-header`,
+`-page`, `-aside`, `-skip`, each a component whose `.css` can be escaped.
+
+A page with `<meta name="layout" content="landing">` takes `layouts/landing.html` instead. It
+starts bare: only the layout elements you put in it are drawn. A missing layout fails the build.
+
+## Project components
+
+A folder under `components/` with a new name adds `<htmlpress-<name>>`, each file named like
+the folder:
+
+```html
+<!-- .htmlpress/components/credits/credits.html -->
+<footer><p>Built by my team · 2026</p></footer>
+```
+
+```css
+/* .htmlpress/components/credits/credits.css */
+@scope (htmlpress-credits) {
+  :scope {
+    display: block;
+  }
+  p {
+    color: var(--htmlpress-muted);
+  }
+}
+```
+
+- The `.html` fills every such tag in the layouts and pages at build time; the tag stays, so its
+  `.css` scopes to it. A custom element is inline until its CSS says otherwise.
+- Its `.css` and `.js` load only where the tag appears. A name is lowercase letters, digits and
+  hyphens.
+- A layout or a component's `.html` may hold any built-in component, but not another project
+  component's tag: it is pasted in once, never rewritten again.
+- The markup inside a layout element (`nav`, `toc`, `pager`, …) is built from the site; a
+  `components/brand/brand.html` replaces it with static HTML, and the built-in `.css` still
+  applies to the tag.
+
+## Rules of thumb
+
+- A misspelt built-in name (`calout/`) adds a component rather than replacing one; a file
+  directly in `components/` fails the build. Check `htmlpress escape` marks the file escaped.
+- To restyle a component from an outer one, beat its `:scope`: write `:scope htmlpress-header`,
+  not a bare `htmlpress-header`, which loses on specificity.
+- Use tokens inside your CSS (`var(--htmlpress-muted)`) so dark mode keeps working.
+
+## Verification
+
+Run `htmlpress build <root> --json` (exit code 0), then `htmlpress start <root>` and look at
+the change in light and dark, wide and phone width. `start` picks up a new or deleted escape
+at once.
+
+## References
+
+- Overriding: https://htmlpress.dev/customization/overriding-escaping.html
+- Layouts: https://htmlpress.dev/customization/custom-routes.html

package/skills/htmlpress-deployment/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: htmlpress-deployment
+description: Use when publishing an htmlpress site — building into .htmlpress/build/, setting site and base, and wiring Cloudflare, GitHub Pages, Vercel, Netlify or any static host, by hand or from CI.
+---
+
+# Htmlpress Deployment
+
+`htmlpress build` writes a fully static site; every host that serves a directory of files can
+serve it. There is no client-side routing, so no host needs an SPA fallback.
+
+## When to use this skill
+
+Invoke when the user asks to:
+
+- Publish the site, or set up a host or a CI deploy.
+- Serve it under a sub-path such as a GitHub Pages project site.
+- Fix a deploy that 404s, loses its styles or misses `sitemap.xml`.
+
+## The build
+
+```sh
+htmlpress build            # or `npx gethtmlpress build` in CI, without installing it
+htmlpress preview          # serves the production build locally, the way a host will
+htmlpress clear            # removes .htmlpress/build
+```
+
+The output is `.htmlpress/build/`: an `.html` per page at its source's path, `404.html`,
+`robots.txt`, `_headers`, a Markdown copy of each page and `llms.txt` for agents, the skills
+under `.well-known/agent-skills/`, the theme under `_htmlpress/`, and every other project file.
+With `site` set it adds `sitemap.xml`. Never edit the output: every build replaces it.
+
+## Config that affects deployment
+
+- `site` — the final origin (`https://docs.example.com`): `sitemap.xml`, canonical URLs and
+  absolute social tags need it.
+- `base` — only for a sub-path (`/my-docs/`). Write links without it; the build prefixes every
+  root-relative URL, and `start` and `preview` serve under it too. A custom domain needs no
+  `base`.
+
+## Hosts
+
+| Host               | Setup                                                                                                                                                           |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Cloudflare Workers | `wrangler.jsonc`: `assets.directory: ".htmlpress/build"`, `html_handling: "none"`, `not_found_handling: "404-page"`; `npx wrangler deploy`                      |
+| GitHub Pages       | `site: https://<user>.github.io`, `base: /<repo>/`; `npx gh-pages -d .htmlpress/build --nojekyll --dotfiles`, or the Pages actions uploading `.htmlpress/build` |
+| Vercel             | `vercel.json`: `"framework": null`, `"buildCommand": "npx gethtmlpress build"`, `"outputDirectory": ".htmlpress/build"`                                         |
+| Netlify            | `netlify.toml`: `[build] command = "npx gethtmlpress build"`, `publish = ".htmlpress/build"`                                                                    |
+| nginx              | `try_files $uri $uri/ =404;` and `error_page 404 /404.html;`                                                                                                    |
+| Caddy              | `file_server` plus `handle_errors { rewrite * /404.html; file_server }`                                                                                         |
+| S3 + CloudFront    | index `index.html`, error `404.html`, a 404 custom error response to `/404.html`                                                                                |
+
+## Rules of thumb
+
+- Point the host's not-found page at `404.html`, so unknown paths keep the site's layout.
+- Keep `html_handling: "none"` on Cloudflare: its default redirects `/guide.html` to `/guide`,
+  away from the URLs htmlpress links to.
+- Keep `--nojekyll` and `--dotfiles` on a GitHub Pages branch deploy: Jekyll drops the
+  `_htmlpress/` theme, and without dot-files `.well-known/` is lost.
+- Files under `_htmlpress/` keep their names between builds: cache them briefly or invalidate
+  them on each release.
+- A project's dot-files are never copied: keep an `.htaccess` on the server.
+
+## Verification
+
+Run `htmlpress build --json` and `htmlpress preview`, then after the deploy open the home page,
+a nested page, an unknown path (the site's 404) and `/robots.txt`. Under a `base`, check that
+styles load and links keep the prefix.
+
+## References
+
+- Deployment: https://htmlpress.dev/deployment/
+- Static hosting: https://htmlpress.dev/deployment/static-hosting.html

package/skills/htmlpress-landing/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: htmlpress-landing
+description: Use when designing or rewriting an htmlpress project's landing page — a layout of its own, hero, sections, screenshots and calls to action as project components, taking htmlpress.dev's own landing as the reference.
+---
+
+# Htmlpress Landing
+
+Guidance for designing the page at `/` of an htmlpress project. The mechanics of a layout and a
+project component are in `htmlpress-customization`; this skill is about what goes on the page.
+
+## When to use this skill
+
+Invoke when the user asks to:
+
+- Build a landing, home or marketing page for the site, or redesign the existing one.
+- Add a hero, feature grid, screenshot carousel or call-to-action section.
+- Make the landing look as polished as htmlpress.dev.
+
+## Start from the reference
+
+htmlpress.dev's landing is itself an htmlpress page with its own layout and a set of project
+components. Read it before writing anything, see it live, and borrow its structure:
+
+- Live: https://htmlpress.dev/
+- Page: https://github.com/datisthq/htmlpress/blob/main/rust/docs/index.html
+- Layout and components: https://github.com/datisthq/htmlpress/tree/main/.htmlpress
+
+None of it is in the packages, so fetch it from GitHub. Take the patterns, not the content:
+rewrite every heading and line of copy for the project, and use the project's own screenshots
+and links. Shipping htmlpress' copy, screenshots or Datist credit on someone else's site is a bug.
+
+## Skeleton
+
+```html
+<!-- index.html -->
+<title>Home</title>
+<meta name="description" content="What the project does, in one line." />
+<meta name="layout" content="landing" />
+<meta name="sidebar" content="false" />
+
+<htmlpress-landing-hero>…</htmlpress-landing-hero>
+<htmlpress-landing-section>…</htmlpress-landing-section>
+<htmlpress-landing-cta>…</htmlpress-landing-cta>
+```
+
+```html
+<!-- .htmlpress/layouts/landing.html -->
+<!doctype html>
+<html lang="en">
+  <head></head>
+  <body>
+    <htmlpress-skip><a href="#content">Skip to content</a></htmlpress-skip>
+    <htmlpress-landing-page>
+      <htmlpress-banner></htmlpress-banner>
+      <htmlpress-header role="banner">
+        <htmlpress-brand></htmlpress-brand>
+        <htmlpress-links></htmlpress-links>
+        <htmlpress-search></htmlpress-search>
+        <htmlpress-theme-toggle></htmlpress-theme-toggle>
+      </htmlpress-header>
+      <main id="content"><htmlpress-content></htmlpress-content></main>
+      <htmlpress-landing-footer></htmlpress-landing-footer>
+    </htmlpress-landing-page>
+    <htmlpress-back-to-top></htmlpress-back-to-top>
+  </body>
+</html>
+```
+
+The reference runs hero → a differentiator ("Stays out of your way") → a feature grid → an
+audience section (agents) → a final call to action → a credit footer. Pick the sections the
+project has something real to say in; three strong ones beat seven thin ones.
+
+## Patterns from the reference
+
+- **One component per block** — `landing-hero`, `-section`, `-features`, `-points`, `-cta`,
+  `-actions`, `-carousel`, `-window`, `-code`, `-backdrop`, `-footer`, `-page`, each a folder
+  under `.htmlpress/components/` with a `.css` scoped to its tag, and `.js` or `.html` only
+  where needed. The page holds semantic HTML inside them: `<section>`, `<header>`, `<hgroup>`,
+  `<h2>`, `<ul>` of `<li>` cards. No classes.
+- **Section shell** — `<htmlpress-landing-section><section><header><h2>` plus a lede, then the
+  body; a two-column section pairs a point list with a visual (`landing-points` beside
+  `landing-window`).
+- **Hero** — a short eyebrow `<p>` in an `<hgroup>` with the `<h1>`, a lede, then
+  `landing-actions` with two links: the docs first, the source second. A decorative
+  `landing-backdrop` takes `aria-hidden="true"`.
+- **Show the product** — real screenshots, not stock art, each shipped light and dark as two
+  `<img>` toggled by the theme with an attribute the component's CSS reads; set `width` and
+  `height` so nothing shifts. `landing-carousel` turns `<section title>` slides into tabs.
+- **Icons** — inline `<svg aria-hidden="true">` with `currentColor` strokes, so they follow the
+  theme.
+- **Colour** — only `--htmlpress-*` tokens and `color-mix(in oklab, …)` of them, so the page
+  rebrands and goes dark with the rest of the site.
+
+## Rules of thumb
+
+- Links are root-relative (`/introduction.html`); `base` is added at build time.
+- Keep the landing out of the sidebar (`sidebar` false) but give it a real `<title>` and
+  `description`: it is the site's social preview.
+- Every component must read well with its JS off: the slides are already in the HTML.
+- Check phone width first; a two-column section must fall back to one.
+
+## Verification
+
+Run `htmlpress build <root> --json`, then `htmlpress start <root>` and look at `/` in light and
+dark, wide and at phone width. Tab through it: the skip link, the actions and the carousel must
+be reachable by keyboard.
+
+## References
+
+- Layouts: https://htmlpress.dev/customization/custom-routes.html
+- Overriding: https://htmlpress.dev/customization/overriding-escaping.html