Intro paragraph and top prompt: first 50 guides

CHANGELOG.md

@@ -12,6 +12,7 @@ service can change a gate's answer, and a pull request number is only knowable f
 
 ## 2026-10-19
 
+- Fifty guides now open with a short paragraph saying what the tool, service or topic is and what the guide helps an AI assistant secure, followed directly by the AI-assistant prompt and then the versions header (maintainer request, 2026-10-19); the end section keeps a short note linking back to the prompt. Each paragraph was drafted by a worker and reviewed against its guide by two model families; guide bodies are otherwise unchanged. `CONTRIBUTING.md` and the `--intro` help no longer call the paragraph human-written (#705)
 - `nodejs.md`, `python.md` and `paas.md`: Railway's listener contract is now cited from its pinned documentation (bind `0.0.0.0` on the injected `PORT`; its edge proxy terminates TLS, and traffic is then forwarded over Railway's internal network to the deployment), and `paas.md`'s redirect bullet links the Railway redirect source inline. Heroku Cedar's listener address, Fly's automatic certificate renewal, the Vercel Functions listener contract and the ACM Private Spaces wildcard question stay open; new TODO rows 1.315 and 1.316 cover two Heroku statements whose cited articles are not yet checked (#704)
 - `docker.md`: the secrets rule now cites pinned Docker documentation for environment-variable risks, `env_file`, Compose secrets and Swarm secrets, and reuses Git's v2.49.0 gitignore citation. It describes Compose secrets as files under `/run/secrets/`, supported on Linux containers only, with access granted per service. Swarm secrets are restricted to swarm services; the secrets are encrypted in transit and at rest, accessible to explicitly authorized services while their tasks run, and mounted in memory in Linux containers. The guide's reasoning distinguishes defining a value in `.env` from setting the container environment, with `environment` and `env_file` examples and interpolation elsewhere in Compose. Offering environment files and ignoring or untracking `.env` are labelled as guide advice; the weaker standing of environment files is labelled as guide assessment. The claim retains the history-source limit; TODO 1.296 moves to DONE, and new row 1.314 carries the `workload` claim's `.gitignore` labelling, untracking and rotation follow-up (#703)
 - The version-basis tooling supports the next guide layout (maintainer ruling, 2026-10-19): a short introduction paragraph under the title, then the line "If an AI assistant is helping you secure a deployment, give it the prompt below:" with the prompt, then the versions and dates paragraph, then the guide; the end-of-file note shrinks to a short explanation with a link back to the prompt, which now appears once; `tools/version_basis.py --introduce` adds a guide's introduction and checks that nothing else in the guide changes; guides keep validating in the current layout until they move, and no guide changes in this PR (#701)

CONTRIBUTING.md

@@ -165,7 +165,7 @@ describing the tool, application or service and explaining that this guide helps
 AI assistant check that it is configured securely. The generated top block follows that
 paragraph: the `ai-assistant-prompt` HTML anchor, the invitation line, the unchanged per-guide
 `text` prompt with its raw URL, and the versions/dates header. The intro is ordinary digested
-body text. The rest of the human body and Sources follow the generated top block.
+body text. The rest of the body and Sources follow the generated top block.
 The single EOF marker pair wraps the fixed H2 "About the AI assistant section below", a
 two-sentence note linking back to the prompt anchor, the summary, and the complete metadata
 in a four-backtick `json` fence. The prompt appears only at the top. END is the last non-blank
@@ -205,16 +205,16 @@ metadata, refusing any difference. It never rebinds. Rebuild both bundles and ru
 the same change as each migration batch. `--check` and `--write` preserve each guide's layout.
 
 For a two-section guide with its generated block immediately after the H1, run
-`python3 tools/version_basis.py --introduce GUIDE --intro 'One human-written paragraph.'`.
-This accepts the historical form as well as a new top prompt without an intro. It validates
-the original guide, inserts the supplied paragraph, moves the prompt/header below it, shortens
-the EOF note and rebinds the digest. Before writing, it asserts that the new body equals the
-old body with only that paragraph and its two separator LFs inserted after the H1, that no
-other metadata changed, and that the result validates and renders identically. It refuses
-legacy front matter, an existing intro before a top prompt, and invalid or stale inputs.
-Review the intro for meaning; paragraph syntax cannot establish human authorship or accuracy.
-Rebuild both bundles and run the gates for each migration batch. This tooling change delivers
-no guide edits.
+`python3 tools/version_basis.py --introduce GUIDE --intro 'The reviewed intro paragraph.'`.
+Intro paragraphs may be drafted by a worker; each is reviewed against its guide before it is
+applied. This accepts the historical form as well as a new top prompt without an intro. It
+validates the original guide, inserts the supplied paragraph, moves the prompt/header below
+it, shortens the EOF note and rebinds the digest. Before writing, it asserts that the new body
+equals the old body with only that paragraph and its two separator LFs inserted after the H1,
+that no other metadata changed, and that the result validates and renders identically. It
+refuses legacy front matter, an existing intro before a top prompt, and invalid or stale
+inputs. Review the intro for meaning; paragraph syntax cannot establish its accuracy. Rebuild
+both bundles and run the gates for each migration batch.
 
 Schema 1 requires exactly these top-level fields:
 

VERSION

@@ -1 +1 @@
-1.0.704
+1.0.705

agent-builders.md

@@ -1,5 +1,23 @@
 # Agent and workflow builders: Dify, Flowise, Langflow, LibreChat
 
+Dify, Flowise, Langflow and LibreChat are tools for building AI chatbots, agents and workflows whose flows can run code and call other services. This guide helps your AI assistant configure each securely, including private binds behind TLS, default secrets replaced, MFA from OIDC or a fronting proxy, and contained flows.
+
+<a id="ai-assistant-prompt"></a>
+
+If an AI assistant is helping you secure a deployment, give it the prompt below:
+
+```text
+Read the secureconfig guide at
+https://raw.githubusercontent.com/jposluns/secureconfig/main/agent-builders.md
+in full, including the section for AI assistants at the end. Then, for my
+deployment: state which of its recommendations apply and the exact changes
+to make; compare the versions the guide was written against with the
+releases I am running and with the vendor's current releases, and flag any
+guidance a newer release may have changed; and run or adapt the guide's
+Verify steps where you can. List separately every item you could not
+verify instead of reporting it as passed.
+```
+
 Written against Dify plugin daemon 0.6.10, Flowise account minimum v3.0.1, Langflow settings source v1.12.6, LibreChat changelog v0.7.7, Docker Compose go.mod v2.24.3, Docker Compose release source v2.24.4, compose-go loader v2.0.0-rc.2, and compose-go reset loader v2.0.0-rc.3; 8 further sources are pinned to a commit and 5 carry no recorded version. Metadata reviewed 2026-10-19; documentation checked September 2026. The guide records 58 claims, all reasoned from cited sources.
 
 A newer release of any of this software can make version-specific details here outdated. To prioritize an update, open a GitHub issue, send a pull request, add a request under [requests/](requests/README.md), or reach the maintainer as [CONTRIBUTING.md](CONTRIBUTING.md) describes. The machine-readable version basis and claim list are in [the section for AI assistants](#about-the-ai-assistant-section-below) at the end of this guide.
@@ -284,23 +302,7 @@ curl -q -g -sS -L --proto-redir '=https' --noproxy '*' --connect-timeout 5 --max
 <!-- version-basis:start -->
 ## About the AI assistant section below
 
-The rest of this file is generated by the repository's tooling and written for AI assistants rather than for people. It records the versions this guide was written against, the guide's claims with a status for each (demonstrated by a check that ran, or reasoned from the cited sources), and the mapping from each claim to its sources. You are welcome to read it, but it is dense and can be hard to take in.
-
-If an AI assistant is helping you secure a deployment, give it the prompt below:
-
-```text
-Read the secureconfig guide at
-https://raw.githubusercontent.com/jposluns/secureconfig/main/agent-builders.md
-in full, including the section for AI assistants at the end. Then, for my
-deployment: state which of its recommendations apply and the exact changes
-to make; compare the versions the guide was written against with the
-releases I am running and with the vendor's current releases, and flag any
-guidance a newer release may have changed; and run or adapt the guide's
-Verify steps where you can. List separately every item you could not
-verify instead of reporting it as passed.
-```
-
-This guide is guidance to verify against your own deployment, not a certification, an audit, or a guarantee of compliance with any standard.
+This generated section holds the recorded versions, claim statuses and source mappings for AI assistants; use [the prompt at the top](#ai-assistant-prompt). This guide is guidance to verify against your own deployment, not a certification, an audit, or a guarantee of compliance with any standard.
 
 **Version basis**
 
@@ -398,7 +400,7 @@ Claims (full source mapping in the JSON block below):
   "schema": 1,
   "checked": "2026-10-19",
   "documentation_checked": "2026-09",
-  "body_sha256": "d9b3ee77e381107c6cb13fbb56ef6cc80dad8ebcffdf662fb0c82608db2cd8f2",
+  "body_sha256": "0d9ea78e5c061542cfce533e70348b663d5fd6fd199aab9cbbff6a99b0b5cefa",
   "components": {
     "daemon": {
       "name": "Dify plugin daemon",

ai-infra-services.md

@@ -1,5 +1,23 @@
 # AI infrastructure services: SearxNG, LocalAI, Text Embeddings Inference, LangServe, Mem0, and Onyx
 
+SearxNG, LocalAI, Text Embeddings Inference, LangServe, Mem0 and Onyx are building blocks for AI apps, from web search to agent memory. This guide helps your AI assistant configure each securely, including authenticated TLS ingress, built-in login or keys enabled where available, and unpublished backing services, apart from deliberate loopback access.
+
+<a id="ai-assistant-prompt"></a>
+
+If an AI assistant is helping you secure a deployment, give it the prompt below:
+
+```text
+Read the secureconfig guide at
+https://raw.githubusercontent.com/jposluns/secureconfig/main/ai-infra-services.md
+in full, including the section for AI assistants at the end. Then, for my
+deployment: state which of its recommendations apply and the exact changes
+to make; compare the versions the guide was written against with the
+releases I am running and with the vendor's current releases, and flag any
+guidance a newer release may have changed; and run or adapt the guide's
+Verify steps where you can. List separately every item you could not
+verify instead of reporting it as passed.
+```
+
 Written against SearxNG documentation (no recorded version), TEI HTTP source v1.9.0, Onyx v4.3 source v4.3.13, Onyx v4.4 source v4.4.0, and GNU grep 3.12; 6 further sources are pinned to a commit and 6 carry no recorded version. Metadata reviewed 2026-10-15; documentation checked September 2026. The guide records 47 claims: 1 demonstrated by a check that ran and 46 reasoned from cited sources.
 
 A newer release of any of this software can make version-specific details here outdated. To prioritize an update, open a GitHub issue, send a pull request, add a request under [requests/](requests/README.md), or reach the maintainer as [CONTRIBUTING.md](CONTRIBUTING.md) describes. The machine-readable version basis and claim list are in [the section for AI assistants](#about-the-ai-assistant-section-below) at the end of this guide.
@@ -494,23 +512,7 @@ The service facts come from the maintainer's vendor-source verification record d
 <!-- version-basis:start -->
 ## About the AI assistant section below
 
-The rest of this file is generated by the repository's tooling and written for AI assistants rather than for people. It records the versions this guide was written against, the guide's claims with a status for each (demonstrated by a check that ran, or reasoned from the cited sources), and the mapping from each claim to its sources. You are welcome to read it, but it is dense and can be hard to take in.
-
-If an AI assistant is helping you secure a deployment, give it the prompt below:
-
-```text
-Read the secureconfig guide at
-https://raw.githubusercontent.com/jposluns/secureconfig/main/ai-infra-services.md
-in full, including the section for AI assistants at the end. Then, for my
-deployment: state which of its recommendations apply and the exact changes
-to make; compare the versions the guide was written against with the
-releases I am running and with the vendor's current releases, and flag any
-guidance a newer release may have changed; and run or adapt the guide's
-Verify steps where you can. List separately every item you could not
-verify instead of reporting it as passed.
-```
-
-This guide is guidance to verify against your own deployment, not a certification, an audit, or a guarantee of compliance with any standard.
+This generated section holds the recorded versions, claim statuses and source mappings for AI assistants; use [the prompt at the top](#ai-assistant-prompt). This guide is guidance to verify against your own deployment, not a certification, an audit, or a guarantee of compliance with any standard.
 
 **Version basis**
 
@@ -593,7 +595,7 @@ Claims (full source mapping in the JSON block below):
   "schema": 1,
   "checked": "2026-10-15",
   "documentation_checked": "2026-09",
-  "body_sha256": "b9931192e8250b1cb318e09284506c74670be8caecc620df4a16d60b15d8d9a0",
+  "body_sha256": "60945815f4a2fd5042b73043af96642c80d50eb23fc37dd84c49f1bf0656d6fe",
   "components": {
     "searx": {
       "name": "SearxNG documentation",

apache.md

@@ -1,5 +1,23 @@
 # Apache HTTP Server: TLS and authentication
 
+Apache HTTP Server is a web server for serving sites over HTTP and HTTPS. This guide helps your AI assistant make sure it is configured securely: the TLS modules enabled, an HTTPS virtual host configured, HTTP redirected to HTTPS, and authentication required where needed.
+
+<a id="ai-assistant-prompt"></a>
+
+If an AI assistant is helping you secure a deployment, give it the prompt below:
+
+```text
+Read the secureconfig guide at
+https://raw.githubusercontent.com/jposluns/secureconfig/main/apache.md
+in full, including the section for AI assistants at the end. Then, for my
+deployment: state which of its recommendations apply and the exact changes
+to make; compare the versions the guide was written against with the
+releases I am running and with the vendor's current releases, and flag any
+guidance a newer release may have changed; and run or adapt the guide's
+Verify steps where you can. List separately every item you could not
+verify instead of reporting it as passed.
+```
+
 Written against Apache HTTP Server 2.4, Apache TLSv1.3 minimum 2.4.36+, Apache per-vhost protocol minimum 2.4.42+, Apache chain-file minimum 2.4.8, httpd htpasswd 2.4.69, OpenSSL qualification 1.1.1+, Certbot Apache installation v2.3.0, and Debian apache2 packaging 2.4.69-1, plus 5 more recorded bases; 1 further source carries no recorded version. Metadata reviewed 2026-10-18; documentation checked September 2026. The guide records 20 claims, all reasoned from cited sources.
 
 A newer release of any of this software can make version-specific details here outdated. To prioritize an update, open a GitHub issue, send a pull request, add a request under [requests/](requests/README.md), or reach the maintainer as [CONTRIBUTING.md](CONTRIBUTING.md) describes. The machine-readable version basis and claim list are in [the section for AI assistants](#about-the-ai-assistant-section-below) at the end of this guide.
@@ -165,23 +183,7 @@ sudo apachectl -S                       # the vhost list, in Apache's own matchi
 <!-- version-basis:start -->
 ## About the AI assistant section below
 
-The rest of this file is generated by the repository's tooling and written for AI assistants rather than for people. It records the versions this guide was written against, the guide's claims with a status for each (demonstrated by a check that ran, or reasoned from the cited sources), and the mapping from each claim to its sources. You are welcome to read it, but it is dense and can be hard to take in.
-
-If an AI assistant is helping you secure a deployment, give it the prompt below:
-
-```text
-Read the secureconfig guide at
-https://raw.githubusercontent.com/jposluns/secureconfig/main/apache.md
-in full, including the section for AI assistants at the end. Then, for my
-deployment: state which of its recommendations apply and the exact changes
-to make; compare the versions the guide was written against with the
-releases I am running and with the vendor's current releases, and flag any
-guidance a newer release may have changed; and run or adapt the guide's
-Verify steps where you can. List separately every item you could not
-verify instead of reporting it as passed.
-```
-
-This guide is guidance to verify against your own deployment, not a certification, an audit, or a guarantee of compliance with any standard.
+This generated section holds the recorded versions, claim statuses and source mappings for AI assistants; use [the prompt at the top](#ai-assistant-prompt). This guide is guidance to verify against your own deployment, not a certification, an audit, or a guarantee of compliance with any standard.
 
 **Version basis**
 
@@ -234,7 +236,7 @@ Claims (full source mapping in the JSON block below):
   "schema": 1,
   "checked": "2026-10-18",
   "documentation_checked": "2026-09",
-  "body_sha256": "645f3f5ab27a4df2af69e0680ac8e98f85ca416fe85a078c95075598e9b33f4d",
+  "body_sha256": "1337f946ff115e07d47b82d92b16b180220ad1d5cada50672a7a286bf5e4bbd3",
   "components": {
     "apache": {
       "name": "Apache HTTP Server",