Use the shared Hub help center instead of a help site in this repo

.github/workflows/ci.yml

@@ -1,6 +1,7 @@
 # Every push and pull request: the shared package's tests, an app build, and a
-# full Help Center build with its link check, so a change that breaks the app
-# or leaves a help page behind can't reach main.
+# check that every Help link the app opens exists in a fresh build of the
+# shared Hub help center, so a change that breaks the app or a help link can't
+# reach main.
 name: CI
 
 on:
@@ -50,20 +51,20 @@ jobs:
             -skipPackagePluginValidation -skipMacroValidation \
             CODE_SIGNING_ALLOWED=NO build
 
-  help:
-    name: Build and check the Help Center
+  help-links:
+    name: Help links resolve in the Hub help center
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
-      - uses: ruby/setup-ruby@v1
+      - uses: actions/checkout@v7
+        with:
+          repository: CompositeCode/substratalapps-applications-specs
+          path: _specs
+      - uses: actions/setup-node@v7
         with:
-          ruby-version: "3.2"
-          bundler-cache: true
-          working-directory: help
-      - name: Generate app-derived pages
-        run: ruby scripts/help-generate.rb --commit "$GITHUB_SHA"
-      - name: Build
-        working-directory: help
-        run: bundle exec jekyll build --destination _site
-      - name: Check every app help link and internal link
-        run: ruby scripts/help-check.rb help/_site
+          node-version: 22
+      - name: Build the help center
+        working-directory: _specs
+        run: npm ci && npm run build
+      - name: Check every screen page and Help menu link
+        run: ruby scripts/help-check.rb _specs/_site/help

.github/workflows/docs-dispatch.yml

@@ -0,0 +1,37 @@
+# Tells the shared Hub help center (CompositeCode/substratalapps-applications-specs)
+# that this app changed, so it rebuilds and republishes straight away instead of
+# waiting for its daily build. That help center is this app's documentation:
+# every Help menu item and screen page the app opens lives there (HelpLinks.swift).
+#
+# Needs the secret SPECS_DOCS_TOKEN: a fine-grained token with Contents: read
+# and write on substratalapps-applications-specs (see that repo's help/README.md
+# → Automation). Without it, this job skips with a notice and the help center
+# still picks changes up on its daily schedule.
+name: Docs dispatch
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "App/**"
+      - "Packages/SubstratalKit/Sources/**"
+      - "CHANGELOG.md"
+      - "project.yml"
+  workflow_dispatch:
+
+jobs:
+  dispatch:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Notify the help center
+        env:
+          GH_TOKEN: ${{ secrets.SPECS_DOCS_TOKEN }}
+        run: |
+          if [ -z "$GH_TOKEN" ]; then
+            echo "::notice::SPECS_DOCS_TOKEN isn't set; the help center will rebuild on its daily schedule."
+            exit 0
+          fi
+          gh api repos/CompositeCode/substratalapps-applications-specs/dispatches \
+            -f event_type=app-docs-updated \
+            -F 'client_payload[app]=macos' \
+            -F "client_payload[sha]=$GITHUB_SHA"

.github/workflows/upstream-sync.yml

@@ -1,12 +1,11 @@
-# Keeps the app and the Help Center in step with their two upstreams:
+# Keeps the app in step with its two upstreams:
 #   - the Platform API's openapi.yaml (CompositeCode/substratalapps.com, main = production)
 #   - the macOS screen inventory (CompositeCode/substratalapps-applications-specs)
 #
 # When either changed, it opens (or updates) one pull request with the new
 # vendored spec and screen catalog. CI then has to build the app's generated
-# client against the new spec and rebuild the Help Center before it can merge,
-# and merging publishes the new docs through help.yml. Nothing reaches main
-# unreviewed.
+# client against the new spec, and check its Help links against the help
+# center, before it can merge. Nothing reaches main unreviewed.
 #
 # Triggers: daily, by hand, or immediately from the upstream repos with a
 # repository_dispatch, for example as a last step of the API's deploy.yml:
@@ -76,11 +75,11 @@ jobs:
           - Platform API \`openapi.yaml\`: **${API}** (from \`CompositeCode/substratalapps.com@main\`)
           - Screen catalog: re-imported from \`CompositeCode/substratalapps-applications-specs\`
 
-          CI rebuilds the generated client against the new spec and rebuilds the Help Center. Before merging:
+          CI rebuilds the generated client against the new spec and checks the app's Help links. Before merging:
           - Breaking changes ship as a new \`Substratal-Version\`. If \`components.parameters.ApiVersion\` gained a value, moving to it is a deliberate code change (\`APIVersion.current\`), not part of this PR.
           - Add a line under **Unreleased** in \`CHANGELOG.md\` if people will notice.
 
-          Merging publishes a new Help Center version.
+          Merging notifies the Hub help center (docs-dispatch.yml), which rebuilds.
           EOF
           )
           if gh pr view "$branch" >/dev/null 2>&1; then

.gitignore

@@ -12,18 +12,5 @@ build/
 .swiftpm/
 Packages/**/Package.resolved.bak
 
-# Help site
-help/_site/
-help/.jekyll-cache/
-help/.sass-cache/
-help/vendor/
-help/.bundle/
-help/_data/versions.yml
-help/_data/build.yml
-help/_data/screens.json
-help/screens/*.md
-!help/screens/index.md
-help/release-notes.md
-
 # macOS
 .DS_Store

App/Navigation/HubCommands.swift

@@ -38,12 +38,14 @@ struct HubCommands: Commands {
             .disabled(navigation == nil)
             Divider()
             Button("Getting Started") { openURL(model.help.gettingStarted) }
-            Button("Tutorials") { openURL(model.help.tutorials) }
+            Button("Using the Hub on macOS") { openURL(model.help.macOSGuide) }
             Button("Keyboard Shortcuts") { openURL(model.help.shortcuts) }
+            Button("Troubleshooting") { openURL(model.help.troubleshooting) }
             Button("Frequently Asked Questions") { openURL(model.help.faq) }
-            Button("Release Notes") { openURL(model.help.releaseNotes) }
+            Button("What's New") { openURL(model.help.whatsNew) }
             Divider()
             Button("API Reference") { openURL(model.help.apiExplorer) }
+            Button("API Versioning") { openURL(model.help.apiVersioning) }
             Button("API Specification") { openURL(HelpLinks.apiSpecification) }
         }
     }

App/Resources/Info.plist

@@ -34,6 +34,6 @@
 	<key>LSMinimumSystemVersion</key>
 	<string>$(MACOSX_DEPLOYMENT_TARGET)</string>
 	<key>SubstratalHelpBaseURL</key>
-	<string>https://compositecode.github.io/substratalapps-macos/</string>
+	<string>https://compositecode.github.io/substratalapps-applications-specs/help/</string>
 </dict>
 </plist>

CHANGELOG.md

@@ -1,6 +1,6 @@
 # Changelog
 
-Every release of Substratal Hub for macOS. The Help Center's Release Notes page is generated from this file. Add an entry under **Unreleased** with every change people will notice; the release workflow moves it under the version number.
+Every release of Substratal Hub for macOS. The Hub help center's What's new page covers every Hub app; this file is the macOS app's own record. Add an entry under **Unreleased** with every change people will notice; the release workflow moves it under the version number.
 
 ## Unreleased
 
@@ -11,7 +11,7 @@ Every release of Substratal Hub for macOS. The Help Center's Release Notes page
 - **Users** (USR-01): search the user directory by name, email or ID, filter by status, and load more as you scroll.
 - **Settings → Appearance**: Match System, Light or Dark, and any of the five light and five dark Substratal themes.
 - **Settings → Connection**: switch between production and a local API devserver. Each keeps its own session.
-- Help menu: Help Center, help for the current screen, tutorials, keyboard shortcuts, FAQ, release notes, and the Platform API reference.
+- Help menu: the Substratal Hub help center (shared by every Hub app), help for the current screen, the macOS guide, keyboard shortcuts, troubleshooting, FAQ, what's new, and the Platform API reference and versioning.
 - Update notices: a banner when this version of the app is deprecated by the API, and a stop with "Update required" when the API no longer supports it.
 
 ### Platform API

Makefile

@@ -30,15 +30,12 @@ sync-api: ## Vendor the latest openapi.yaml from the API repo's main
 sync-screens: ## Re-import the screen catalog from ../substratalapps-applications-specs
 	ruby scripts/import-screens.rb
 
-help-build: ## Build the Help Center locally and check its links
-	ruby scripts/help-generate.rb
-	cd help && bundle install --quiet && bundle exec jekyll build
-	ruby scripts/help-check.rb help/_site
+SPECS ?= ../substratalapps-applications-specs
 
-help-serve: ## Serve the Help Center at http://localhost:4000/substratalapps-macos/
-	ruby scripts/help-generate.rb
-	cd help && bundle install --quiet && bundle exec jekyll serve --livereload
+help-check: ## Check the app's Help links against a fresh build of the Hub help center in SPECS
+	cd $(SPECS) && npm ci --silent && npm run build
+	ruby scripts/help-check.rb $(SPECS)/_site/help
 
-check: test build help-build ## Everything CI runs
+check: test build help-check ## Everything CI runs
 
-.PHONY: help project build run test ui-test sync-api sync-screens help-build help-serve check
+.PHONY: help project build run test ui-test sync-api sync-screens help-check check

Packages/SubstratalKit/Sources/SubstratalKit/Help/HelpLinks.swift

@@ -1,15 +1,18 @@
 import Foundation
 
-/// Links into the Hub Help Center (the `help/` site in this repo, published to
-/// GitHub Pages). Every screen has a page at `screens/<id>/`, generated from the
-/// same `screens.json` the app navigates with, so a Help button can never point
-/// at a page that doesn't exist.
+/// Links into the Substratal Hub help center, the one documentation reference
+/// every Hub app shares. It's built from the specs repository
+/// (`CompositeCode/substratalapps-applications-specs`, `help/` and
+/// `site/help.mjs`) and published at `…/substratalapps-applications-specs/help/`.
+/// Every screen has a page at `screens/<id>.html`, generated from the same
+/// spec this app's screen catalog is imported from. CI checks that every link
+/// here exists in a fresh build of that site (`scripts/help-check.rb`).
 public struct HelpLinks: Sendable {
-    public static let defaultBase = URL(string: "https://compositecode.github.io/substratalapps-macos/")!
+    public static let defaultBase = URL(string: "https://compositecode.github.io/substratalapps-applications-specs/help/")!
 
     public let base: URL
 
-    /// `base` comes from Info.plist `SubstratalHelpBaseURL` so a staging build can
+    /// `base` comes from Info.plist `SubstratalHelpBaseURL`, so a build can
     /// point at a preview of the site.
     public init(base: URL = HelpLinks.defaultBase) {
         self.base = base
@@ -20,22 +23,27 @@ public struct HelpLinks: Sendable {
         self.init(base: configured ?? Self.defaultBase)
     }
 
-    public var home: URL { base }
-    public var gettingStarted: URL { page("getting-started/") }
-    public var tutorials: URL { page("tutorials/") }
-    public var faq: URL { page("faq/") }
-    public var shortcuts: URL { page("reference/keyboard-shortcuts/") }
-    public var apiReference: URL { page("api/") }
-    /// Swagger UI over the vendored openapi.yaml.
-    public var apiExplorer: URL { page("api/reference/") }
-    public var releaseNotes: URL { page("release-notes/") }
-
-    public func screen(_ id: String) -> URL { page("screens/\(id.lowercased())/") }
+    public var home: URL { page("index.html") }
+    public var gettingStarted: URL { page("guides/getting-started.html") }
+    /// Shortcuts, windows, the Keychain and Settings → Connection.
+    public var macOSGuide: URL { page("guides/macos.html") }
+    public var shortcuts: URL { page("guides/macos.html", fragment: "keyboard-shortcuts") }
+    public var troubleshooting: URL { page("guides/troubleshooting.html") }
+    public var faq: URL { page("faq.html") }
+    public var whatsNew: URL { page("whats-new.html") }
+    public var apiQuickstart: URL { page("developers/quickstart.html") }
+    public var apiVersioning: URL { page("developers/api-versioning.html") }
+    /// Swagger UI for the API version this build speaks.
+    public var apiExplorer: URL { page("api/v\(APIVersion.headerValue)/index.html") }
+
+    public func screen(_ id: String) -> URL { page("screens/\(id.lowercased()).html") }
 
     /// The API's own specification site (system of record for the contract).
     public static let apiSpecification = URL(string: "https://compositecode.github.io/substratalapps.com/")!
 
-    private func page(_ path: String) -> URL {
-        URL(string: path, relativeTo: base)!.absoluteURL
+    private func page(_ path: String, fragment: String? = nil) -> URL {
+        var components = URLComponents(url: URL(string: path, relativeTo: base)!.absoluteURL, resolvingAgainstBaseURL: true)!
+        components.fragment = fragment
+        return components.url!
     }
 }