Repository navigation
Conversation
App (GTK 4 + libadwaita, Rust): - substratal-core: API client that sends Substratal-Version: 1 to the host root (no /v1), with single-flight refresh, idempotency keys, If-Match, retries, error-envelope decoding, and Deprecation/Sunset -> "Update available"/"Update required"; Secret Service storage; Capabilities; the screen registry (all 75 Hub screens plus the 12 web-only Console screens) generated from the specs; navigation and visibility rules; shortcuts. - substratal-hub: window shell with gated sidebar, router and substratal:// links, Blueprint sign-in with 2FA, themes (5 light, 5 dark), command palette, shortcuts dialog, F1 help per screen, spec-driven scaffolds for every screen, and live Users, Account and Settings > Appearance screens. - substratalctl: CLI on the same core. Help center (docs/, Jekyll + just-the-docs) for every Hub app: guides, tutorials, FAQ, a page per screen, API versioning and auth, Swagger UI with a Substratal-Version picker, every API operation cross-linked to the screens using it, and versioned snapshots like the API docs. Reference pages are generated from the code by `cargo xtask gen-docs`. Automation: CI (fmt, clippy, tests, generated-docs and spec checks), docs build + GitHub Pages deploy on every change to main, API spec sync (oasdiff changelog, PR) and client specs sync, Flatpak builds. Plans moved to planning/, with a prerequisites check and dated updates for header versioning and the web-only Console (specs OPEN-QUESTIONS #27). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The Flatpak SDK's cargo rejects overriding default-features of a workspace dependency, so the workspace now declares substratal-core without default features and the app and CLI enable keyring. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The Hub help center (help/ in CompositeCode/substratalapps-applications-specs) is the one documentation site for every Hub app, so this repo no longer builds its own: - Remove docs/, scripts/docs-build.rb and the Pages deploy workflow. - Help links (F1, Help buttons, About, AppStream) open .../substratalapps-applications-specs/help/, screens at help/screens/<id>.html. - xtask gen-docs becomes gen-help: it writes the Linux pages that come from this code (keyboard shortcuts, substratalctl) into the specs repo's help/. The Linux guide and these pages are in substratalapps-applications-specs PR #3. - New docs-dispatch workflow: on push to main, regenerate those pages, open a PR in the specs repo and send app-docs-updated (needs SPECS_DOCS_TOKEN). - API spec sync now only updates vendor/openapi.yaml (with the oasdiff changelog in the PR); the help center builds its API reference from the live spec. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this adds
Prerequisites: checked and recorded in
planning/PREREQUISITES.md, including the API versioning change. The version is theSubstratal-Version: 1header, URLs have no/v1, and/v1/...returns 404. This was verified against production.App skeleton: GTK 4 + libadwaita, Rust.
substratal-coreis GTK-free:If-Match, and retriesDeprecation/Sunsethandling that drives "Update available" and "Update required"substratal-hub:substratal://deep linkssubstratalctlis a CLI on the same core.Help: moved to the Hub help center in the specs repo, the one documentation site for every Hub app (CompositeCode/substratalapps-applications-specs#3). The Linux guide, the Linux keyboard shortcuts and the
substratalctlreference are there; the last two are generated from this code bycargo xtask gen-help. The app's F1 and Help buttons open…/substratalapps-applications-specs/help/screens/<id>.html. This repo no longer builds its own site.Automation:
ci.yml): fmt, clippy with-D warnings, tests, checks that spec-derived files and the Linux help pages are current, and desktop/AppStream validation.docs-dispatch.yml): on every merge tomain, regenerates the Linux help pages, opens a PR in the specs repo, and sendsapp-docs-updatedso the help center rebuilds. Needs theSPECS_DOCS_TOKENsecret.api-spec-sync.yml): runs every 6 hours or on demand. It updatesvendor/openapi.yamland opens a PR with the oasdiff changelog, labelled when there's a breaking change.specs-sync.yml): runs daily.flatpak.yml): builds the bundle on GNOME 50.Verified locally (Ubuntu 24.04 container: GTK 4.14.5, libadwaita 1.5.0)
cargo fmt --check,cargo clippy -D warnings, andcargo test: 34 tests pass. 7 of them drive the HTTP client against a stub server to check the version header, deprecation handling, update-required, refresh on 401, idempotency andIf-Match.substratalctlagainst production:healthreturns ok, and errors carry their request ID.Not covered yet
🤖 Generated with Claude Code