From dcb99736e2346741e20a559ba8c3b4b5a8bef7d8 Mon Sep 17 00:00:00 2001
From: Jason Grey <jason@jason-grey.com>
Date: Thu, 27 Aug 2026 18:37:39 -0500
Subject: [PATCH] docs: clarify CMS status and signing

---
 README.md      | 42 ++++++++++++++++++++++++++++++++----------
 hugo/README.md |  6 ++++--
 2 files changed, 36 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index d9f7c00..2695524 100644
--- a/README.md
+++ b/README.md
@@ -1,16 +1,44 @@
 # HTMLTrust CMS Reference
 
-Reference CMS plugin for server-side content signing with HTMLTrust. Embeds cryptographic signatures into published content so that browsers and crawlers can verify authorship and integrity.
+Reference WordPress and Hugo integrations for HTMLTrust content signing. They prepare published content for canonical hashing and embed signatures that browsers and crawlers can verify.
 
 This is a companion to the [HTMLTrust specification](https://github.com/HTMLTrust/htmltrust-spec).
 
+## Current status
+
+The WordPress plugin and Hugo build integration are runnable. Drupal, Joomla, and Craft integrations are planned but have no code in this repository yet.
+
+## WordPress prerequisites
+
+- WordPress 5.0+
+- PHP 7.2+
+- PHP Intl extension
+- Composer
+- A running [HTMLTrust trust directory server](https://github.com/HTMLTrust/htmltrust-server-reference)
+
+## Quick start
+
+### WordPress
+
+```sh
+cd wordpress/
+composer install
+```
+
+Symlink the `wordpress/` directory into `wp-content/plugins/`, or zip it and install it through the WordPress admin. Configure a server profile, link a WordPress user to a registered author identity, and enable signing for the post types you want to publish.
+
+### Hugo
+
+Copy the partials from `hugo/layouts/partials/` into your Hugo project, then follow the [Hugo integration guide](hugo/README.md) to wrap selected pages and run the optional post-build signer.
+
 ## What It Does
 
 When an author publishes content, the plugin:
 
-- **Normalizes** the content (strips markup, collapses whitespace) and computes a SHA-256 content hash
-- **Signs** the hash via the HTMLTrust trust directory API using the author's private key
-- **Embeds** the signature, author public key reference, and content hash into the published HTML
+- **Canonicalizes** rendered content, including signed semantic attributes, and computes a SHA-256 content hash
+- **Builds** direct-child claims, computes their canonical claims hash, and binds both hashes to the publication origin and signed-at timestamp
+- **Requests** a compatibility signature from the HTMLTrust trust directory using the configured author API credential; the server performs signing for the registered author identity
+- **Embeds** the signature, key reference, algorithm, content hash, signed-at claim, and direct-child claims into the published HTML
 - **Supports** multiple author profiles, endorser profiles, and claim metadata (content type, license, AI involvement, etc.)
 - **Displays** signature status on the frontend with verification controls
 
@@ -47,12 +75,6 @@ htmltrust-cms-reference/
 
 ## WordPress Plugin
 
-### Prerequisites
-
-- WordPress 5.0+
-- PHP 7.2+
-- A running [HTMLTrust trust directory server](https://github.com/HTMLTrust/htmltrust-server-reference)
-
 ### Installation
 
 ```sh
diff --git a/hugo/README.md b/hugo/README.md
index 2dc7811..ac84188 100644
--- a/hugo/README.md
+++ b/hugo/README.md
@@ -75,6 +75,8 @@ Run the post-build script to add the required `content-hash`, `signature`, `keyi
 
 To add spec-conformant content hashes and full cryptographic signatures, use the post-build script after `hugo build`:
 
+Copy `scripts/sign-site.mjs` from this integration into your Hugo project's `scripts/` directory first. The script uses only Node.js built-ins and needs no package install.
+
 ```sh
 hugo --minify
 node scripts/sign-site.mjs --dir public
@@ -96,10 +98,10 @@ The script finds existing `<signed-section>` elements (already wrapping the cont
 ```
 hugo/
 ├── layouts/partials/
-│   ├── htmltrust-signed-section.html   # Core: computes hash, outputs <signed-section>
+│   ├── htmltrust-signed-section.html   # Wraps selected content in <signed-section>
 │   └── htmltrust-meta.html             # Optional: emits <meta> tags in <head>
 ├── scripts/
-│   └── sign-site.mjs                   # Optional: post-build API signing
+│   └── sign-site.mjs                   # Computes hashes and requests API signatures
 └── README.md
 ```