feat(dev,html-app): make one-page HTML apps more consistent and discoverable

Author: azasypkin

.env.example

@@ -39,10 +39,44 @@ COURIER_HTTP_REQUEST_CONFIG_AUTH_CONFIG_VALUE="Bearer <generated-kratos-jwt>"
 # HTML tool app deployment (dev/tools/)
 # SECUTILS_HTML_APP_API_DOMAIN=https://secutils.dev
 # SECUTILS_HTML_APP_API_KEY=su_ak_...
+#
+# Public host where the tools are served. Used by `dev/tools/deploy.ts` to substitute `{{TOOLS_HOST}}` placeholders in
+# HTML and skill .md sources before minification (canonical, og:url, og:image, JSON-LD, related-tools links, llms.txt
+# entries). Defaults to `tools.secutils.dev`.
+# SECUTILS_TOOLS_PUBLIC_HOST=tools.secutils.dev
+#
+# Absolute path (or path relative to this repo root) to the marketing site's index.html. Read by
+# `scripts/tools-check.ts` to verify that every promoted tool is linked from the home page's "Free single-page tools"
+# section, and that no non-promoted tool leaked there. The marketing site lives in a separate (private) sibling
+# checkout. When unset the marketing-side check is skipped with a warning so contributors without that checkout can
+# still run `make tools-check`.
+# SECUTILS_TOOLS_PROMO_HOME_INDEX=../<promo-repo>/.../src/index.html
+#
+# Per-tool responder IDs. Each tool has two sibling responders:
+#   _<TOOL>     -> serves `https://<TOOLS_HOST>/<path>`     (text/html)
+#   _<TOOL>_MD  -> serves `https://<TOOLS_HOST>/<path>.md`  (text/markdown,  the AI agent skill)
+# Plus the agent-discovery singletons:
+#   _LLMS_TXT            -> /llms.txt                          (text/markdown,     llmstxt.org index)
+#   _ROBOTS_TXT          -> /robots.txt                        (text/plain,        AI crawler rules + Content Signals + sitemap pointer)
+#   _SITEMAP_XML         -> /sitemap.xml                       (application/xml,   one entry per public surface)
+#   _AGENT_SKILLS_INDEX  -> /.well-known/agent-skills/index.json (application/json, Cloudflare Agent Skills Discovery RFC v0.2.0)
+#
+# Tools whose source HTML lacks a responder ID are skipped at deploy with a
+# yellow warning (existing behavior; this lets you stage rollouts safely).
 # SECUTILS_HTML_APP_RESPONDER_ID_INDEX=
-# SECUTILS_HTML_APP_RESPONDER_ID_CALC=
 # SECUTILS_HTML_APP_RESPONDER_ID_JWT_DEBUGGER=
+# SECUTILS_HTML_APP_RESPONDER_ID_JWT_DEBUGGER_MD=
 # SECUTILS_HTML_APP_RESPONDER_ID_SAML_DECODER=
+# SECUTILS_HTML_APP_RESPONDER_ID_SAML_DECODER_MD=
 # SECUTILS_HTML_APP_RESPONDER_ID_MOCK_SAML_IDP=
+# SECUTILS_HTML_APP_RESPONDER_ID_MOCK_SAML_IDP_MD=
 # SECUTILS_HTML_APP_RESPONDER_ID_CERTIFICATE_DECODER=
+# SECUTILS_HTML_APP_RESPONDER_ID_CERTIFICATE_DECODER_MD=
 # SECUTILS_HTML_APP_RESPONDER_ID_MARKDOWN_TO_HTML=
+# SECUTILS_HTML_APP_RESPONDER_ID_MARKDOWN_TO_HTML_MD=
+# SECUTILS_HTML_APP_RESPONDER_ID_ECHO=
+# SECUTILS_HTML_APP_RESPONDER_ID_ECHO_MD=
+# SECUTILS_HTML_APP_RESPONDER_ID_LLMS_TXT=
+# SECUTILS_HTML_APP_RESPONDER_ID_ROBOTS_TXT=
+# SECUTILS_HTML_APP_RESPONDER_ID_SITEMAP_XML=
+# SECUTILS_HTML_APP_RESPONDER_ID_AGENT_SKILLS_INDEX=

.gitignore

@@ -13,3 +13,6 @@ dist
 *.private.env.json
 deploy.env
 secutils.toml
+
+# Generated by `dev/tools/deploy.ts` from the *.skill.md sources at deploy time.
+dev/tools/llms.txt

Makefile

@@ -20,7 +20,7 @@ DEPLOY_CAMOUFOX_TAG 	?=
 .PHONY: deploy-dev deploy-dev-api deploy-dev-webui deploy-dev-docs deploy-dev-retrack-api deploy-dev-retrack-scraper
 .PHONY: deploy-prod deploy-prod-api deploy-prod-webui deploy-prod-docs deploy-prod-retrack-api deploy-prod-retrack-scraper
 .PHONY: deploy-camoufox
-.PHONY: deploy-tools
+.PHONY: deploy-tools tools-og tools-og-loop tools-check e2e-tools-test
 
 ## ---------- Development ----------
 
@@ -244,9 +244,34 @@ perf-report: ## Open the HTML perf viewer. Load .perf/history.jsonl inside it.
 
 ## ---------- Tool Apps ----------
 
-deploy-tools: ## Deploy dev/tools HTML apps to responders (ARGS="calc jwt-debugger" to deploy specific tools).
+deploy-tools: ## Deploy dev/tools HTML apps to responders (ARGS="jwt-debugger echo" to deploy specific tools; also handles *.skill.md and llms.txt).
 	node --env-file=.env dev/tools/deploy.ts $(ARGS)
 
+tools-og: ## Regenerate the per-tool 1200x630 OG images (dark + light) into components/secutils-docs/static/img/og/.
+	cd e2e && npx playwright test --config=playwright.tools.config.ts og.spec.ts $(ARGS)
+
+tools-og-loop: ## Run tools-og repeatedly to verify OG screenshots are byte-stable (RUNS=N default 10).
+	@rm -rf $(E2E_LOOP_DIR) && mkdir -p $(E2E_LOOP_DIR); \
+	pass=0; fail=0; \
+	for i in $$(seq 1 $(RUNS)); do \
+		echo "--- Run $$i/$(RUNS) ---"; \
+		rm -rf e2e/test-results; \
+		if (cd e2e && npx playwright test --config=playwright.tools.config.ts og.spec.ts $(ARGS)) > $(E2E_LOOP_DIR)/run-$$i.log 2>&1; then \
+			pass=$$((pass+1)); echo "PASS"; \
+		else \
+			fail=$$((fail+1)); echo "FAIL  →  $(E2E_LOOP_DIR)/run-$$i.log"; \
+			[ -d e2e/test-results ] && cp -r e2e/test-results $(E2E_LOOP_DIR)/artifacts-run-$$i || true; \
+		fi; \
+	done; \
+	echo "=== Results: $$pass/$(RUNS) passed, $$fail/$(RUNS) failed ==="; \
+	echo "Logs and artifacts: $(E2E_LOOP_DIR)"
+
+e2e-tools-test: ## Run the e2e/tools/ Playwright suite against $(BASE_URL) (default https://tools.secutils.dev). Use ARGS for extra flags.
+	cd e2e && npx playwright test --config=playwright.tools.config.ts $(ARGS)
+
+tools-check: ## Validate that the promo home Free-tools section matches `<meta name="su-tool-promote">` in dev/tools/. Read-only, no browser.
+	@node scripts/tools-check.ts
+
 ## ---------- Docker Cleanup ----------
 
 docker-df: ## Show Docker disk usage summary.

README.md

@@ -30,10 +30,24 @@ Secutils.dev adheres to [open security principles](https://en.wikipedia.org/wiki
 
 ![Secutils.dev Web Security](https://github.com/secutils-dev/.github/blob/main/profile/web_security.png?raw=true)
 
+## Free single-page tools
+
+A handful of focused, no-signup, browser-only tools is hosted at [tools.secutils.dev](https://tools.secutils.dev/). Every tool ships with a stable shareable URL (drop a link into a ticket, an MCP agent, or a postmortem) and an AI-agent skill at `/<slug>.md` so coding assistants can drive the tool directly from a `WebFetch` call.
+
+| Tool                                                              | What it does                                                       | AI-agent skill                                                |
+|-------------------------------------------------------------------|--------------------------------------------------------------------|---------------------------------------------------------------|
+| [JWT Debugger](https://tools.secutils.dev/jwt)                    | Decode, verify, and sign HMAC JSON Web Tokens                      | [`/jwt.md`](https://tools.secutils.dev/jwt.md)                |
+| [SAML Decoder](https://tools.secutils.dev/saml)                   | Inspect SAML responses, requests, and metadata                     | [`/saml.md`](https://tools.secutils.dev/saml.md)              |
+| [PEM Certificate Decoder](https://tools.secutils.dev/pem)         | Inspect PEM-encoded X.509 certificate chains                       | [`/pem.md`](https://tools.secutils.dev/pem.md)                |
+| [Markdown to HTML](https://tools.secutils.dev/md-to-html)         | Self-contained HTML and PDF export from Markdown                   | [`/md-to-html.md`](https://tools.secutils.dev/md-to-html.md)  |
+| [HTTP Echo / Mock Response](https://tools.secutils.dev/echo)      | Build a customizable HTTP response, served as a shareable URL      | [`/echo.md`](https://tools.secutils.dev/echo.md)              |
+
+The aggregate index of all skills (including specialized ones not listed above) is published at [tools.secutils.dev/llms.txt](https://tools.secutils.dev/llms.txt) following the [llmstxt.org](https://llmstxt.org/) convention. Source HTML for every tool lives in [`dev/tools/`](dev/tools/) (see [`dev/tools/AGENTS.md`](dev/tools/AGENTS.md) for the deploy/SEO recipe).
+
 ## Prerequisites
 
 - [Rust](https://www.rust-lang.org/tools/install) (stable toolchain)
-- [Node.js](https://nodejs.org/) 22+ (see `.nvmrc`)
+- [Node.js](https://nodejs.org/) 24+ (see `.nvmrc`)
 - [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/install/)
 
 ## Getting Started