Substratal Apps Substratal Apps Hub specs
GitHub

Help Developers

Developers

Linking to help from an app

Every Hub app links into this help center the same way, so a screen's help address is identical on all platforms.

URLs

Page URL, relative to https://compositecode.github.io/substratalapps-applications-specs/help/
A screen screens/<screen-id-lowercase>.html, e.g. screens/usr-01.html
Help home index.html
A guide or tutorial guides/<slug>.html, tutorials/<slug>.html
FAQ faq.html
API reference api/v<Substratal-Version>/index.html
Search search.html
Every screen, by area screens/index.html
Endpoint index (no JavaScript needed) api/v<Substratal-Version>/endpoints.html
Every API spec revision and what changed api/revisions.html
The search index, for in-app help search search-index.json (served with Access-Control-Allow-Origin: *)

Screen IDs come from SCREEN-SPECS.md and never change meaning. Open help in the platform's in-app browser (Custom Tabs on Android, SFSafariViewController on iOS). Make the base URL a build setting, so a staging build can point at a preview.

Don't link to screens an app adds on its own, outside the design package: they have no help page. Web-only Console screens (domain C) are linked from the web app only.

Reporting build status

Each screen page's On your platform table shows how far each app has got with that screen. An app reports this in help/apps/<platform>.json:

{
  "platform": "android",
  "app": "CompositeCode/substratalapps-android",
  "app_version": "0.1.0",
  "api_version": "1",
  "screens": { "USR-01": "available", "APL-01": "available" }
}
  • screens maps screen IDs to available or preview. Anything not listed is shown as planned.
  • The build checks the file: unknown screen IDs, Console screens listed by a native app, or unknown states are reported in coverage.html, and fail pull requests.
  • Generate the file from the app's own code, so it can't drift. The Android app runs ./gradlew :core:model:exportHelp. Its help-status workflow opens a pull request here whenever the file changes, then sends the app-docs-updated dispatch (see help/README.md).

Android reference implementation

HelpLinks in the Android app builds these URLs from BuildConfig.HELP_BASE_URL and each screen's ID, and every screen's top bar opens its page. See the app's README for how the catalog, the navigation and the status file are kept in step.

How this help center stays current

  • Generated from the source. Screen pages, the endpoint index, the API reference and the search index are rebuilt from the specs and the live openapi.yaml on every build, so they can't drift.
  • Checked on every pull request. Pull requests build with HELP_STRICT=1, which fails on:
    • guides that name unknown screens
    • API operations missing from the screen map, or removed from the API
    • invalid app status files
  • Rebuilt when things change. The site is rebuilt when an app repository or the API sends a repository_dispatch (app-docs-updated, api-contract-updated), and daily in case one is missed.
  • New API revisions arrive by pull request. An hourly workflow records each new spec revision and what changed in it, then opens a pull request.

Last updated 2026-10-24 · Built 2026-10-25 from a9ef3be · API 1.0.0-draft.13 · Substratal-Version: 1