gethtmlpress 0.0.0 → 0.2.0

package/README.md

@@ -1,3 +1,49 @@
-# gethtmlpress
+# Htmlpress
 
-Placeholder. [htmlpress](https://htmlpress.dev) ships on npm from 0.1.0.
+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,8 +1,40 @@
 {
   "name": "gethtmlpress",
-  "version": "0.0.0",
-  "description": "Placeholder; htmlpress ships from 0.1.0",
-  "license": "MIT",
+  "version": "0.2.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",
-  "repository": { "type": "git", "url": "git+https://github.com/datisthq/htmlpress.git", "directory": "typescript" }
+  "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.2.0",
+    "@htmlpress/linux-arm64": "0.2.0",
+    "@htmlpress/darwin-x64": "0.2.0",
+    "@htmlpress/darwin-arm64": "0.2.0",
+    "@htmlpress/win32-x64": "0.2.0",
+    "@htmlpress/win32-arm64": "0.2.0"
+  }
 }

package/skills/htmlpress-authoring/SKILL.md

@@ -0,0 +1,157 @@
+---
+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; a
+  fragment's are the ones before its first content, as a browser reads them.
+- 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 and whose `order` places the folder.
+- Each page is served at its own folder URL: `guides/build.html` at `/guides/build/`,
+  `guides/index.html` at `/guides/`. Link to the page file (`guides/build.html`, relative or
+  root-relative) or to its URL: a link naming a page's file becomes its URL. Images and other
+  files are copied as-is; a relative `href`, `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                                         |
+| `breadcrumbs` (`false` / `true`)             | hides or shows the folder trail, over the config's           |
+| `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. Without a translated home,
+`/<code>/` redirects to the language's first page.
+
+## 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/#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 start <root> --json   # {"url": "...", "network": []} on one line once serving
+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/
+- Code blocks: https://htmlpress.dev/authoring/code-blocks/

package/skills/htmlpress-configuration/SKILL.md

@@ -0,0 +1,127 @@
+---
+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>
+breadcrumbs: false
+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).
+- `breadcrumbs` — `false` hides the folder trail above every page; default `true`, and a
+  page's `<meta name="breadcrumbs">` overrides it.
+- `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`, `breadcrumbs`, `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/
+- Sections: https://htmlpress.dev/customization/article-sections/
+- Translations: https://htmlpress.dev/customization/translations/
+- Versioning: https://htmlpress.dev/customization/versioning/
+- Patches: https://htmlpress.dev/customization/article-patches/

package/skills/htmlpress-customization/SKILL.md

@@ -0,0 +1,139 @@
+---
+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), `<htmlpress-shortcuts>` (the keyboard shortcuts menu, listing every key and disabling the ones no
+control on the page announces with `aria-keyshortcuts`) 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. The theme toggle, the
+language picker and the sidebar's section picker drop down from `56rem` up and, like the
+contents bar, open an `<htmlpress-sheet>` on a phone: one bottom sheet the scripts append to
+`<body>`, so escape `components/sheet/sheet.css` to restyle every sheet at once.
+
+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/
+- Layouts: https://htmlpress.dev/customization/custom-routes/

package/skills/htmlpress-deployment/SKILL.md

@@ -0,0 +1,71 @@
+---
+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 `index.html` per page in its own folder
+(`guides/build.html` at `guides/build/index.html`), `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"`, `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 `--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/

package/skills/htmlpress-landing/SKILL.md

@@ -0,0 +1,112 @@
+---
+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/`, or the file, `/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/
+- Overriding: https://htmlpress.dev/customization/overriding-escaping/