docs: sync with branding white-label, SM022/SM023, Docker scaffold - #255
Merged
Conversation
…3, Docker scaffold) The docs had drifted behind several merged features: - modules/branding: rewritten. The page still described the pre-#237 module (name, logo, favicon, colour). Adds the dark-background logo variant, design pack, announcement banner, configurable footer + its limits and href allow-list, presets, the anonymous asset routes and their cache policy, and the magic-number upload check. Corrects the allowed-types list, which still advertised image/svg+xml — SVG is excluded on purpose (XML that can carry <script>, i.e. stored XSS from our own origin). - reference/diagnostic-codes: add the missing SM022/SM023 rows. Every other code in the framework was documented; these two shipped with #238. - framework/discovery: document i18n_audience and requires_framework in the ModuleMeta section, cross-linked to the i18n page. - reference/deployment: the Build section told operators to hand-roll a Dockerfile that every scaffold has shipped since #252 — and the example used a Node-only frontend stage, which cannot work, since gen-pages reads the installed Python modules. Replaced with the shipped assets plus why the single builder stage is load-bearing. - alembic upgrade head -> heads across guide/reference. Every real command (Makefile, smpy new, the container CMD) uses the plural; the singular errors once a second module ships a branch label. - Module count eleven -> twelve; branding was missing from the home page list, and its index row predated the white-label work. Verified: vitepress build clean, and the four cross-page anchors checked against the generated HTML (ignoreDeadLinks is on, so the build itself does not catch them). Claude-Session: https://claude.ai/code/session_013W1MJ3T4FJEBcx1Xs9Tea2
- branding: the magic-number check was overstated. validate_image matches the head against *any* allowed signature, not the one the declared Content-Type implies, so a genuine PNG sent as image/jpeg passes and is stored as image/jpeg. Reworded to the property that actually holds (non-images are kept out) rather than type/content agreement. - branding: the file_storage download permission is `file_storage.download`, not `file-storage.download`. Copied the hyphen from the stale comment at branding/constants.py:76; the constant is FileStoragePermissions.DOWNLOAD. - framework/overview: module count said "ten first-party modules" — missed in the eleven -> twelve sweep, so two pages one click apart disagreed. - module-authoring: one more `alembic upgrade head` -> `heads`, in the publish-a-module flow whose very next subsection tells the author to add branch_labels — i.e. exactly the case the plural exists for. - deployment: the new "run make docker-up" Build section sat three lines under a checklist item requiring Postgres, while the default SQLite compose pins SM_ENVIRONMENT=production *and* a SQLite URL. Added a warning that the SQLite stack is local/demo only, and why it isn't a one-env-var swap (migration histories are dialect-frozen). Also fixes the scaffold README template, which shipped `upgrade head` into every generated project while that project's own Makefile and Dockerfile use `heads`. test_cli_new_scaffold_layout already asserts the singular form is gone from the Makefile, so the README was simply missed. Verified: 216 CLI tests pass, vitepress build clean. Claude-Session: https://claude.ai/code/session_013W1MJ3T4FJEBcx1Xs9Tea2
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
1 participant
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.
Documentation had drifted behind several merged features. This brings it back in line and fixes accuracy problems found along the way.
What was stale
docs/modules/branding.md— the page still described the pre-#237 module (name, logo, favicon, colour). Rewritten to cover the dark-background logo variant, design pack, announcement banner, configurable footer (limits + thehttp(s)-or-app-path href allow-list), presets, the anonymous asset routes and their versioned cache policy, the asset lifecycle, and the upload guard-rails.It also advertised
image/svg+xmlas an allowed upload type, which is wrong and security-relevant — SVG is excluded on purpose, being XML that can carry<script>and would be served back from the app's own origin.docs/reference/diagnostic-codes.md— SM022/SM023 (shipped in #238) were the only framework codes with no rows.docs/reference/deployment.md— the Build section told operators to hand-roll a Dockerfile that every scaffold has shipped since #252. Worse, the example used a Node-only frontend stage, which cannot work: the Vite build importsmodules.generated.{ts,css}, whichgen-pagesemits from the installed Python modules. Replaced with the shipped assets and why the single builder stage is load-bearing.alembic upgrade head→headsacross guide and reference. Every real command — Makefile,smpy new, the containerCMD— uses the plural; the singular errors once a second module ships a branch label.test_cli_new_scaffold_layoutalready calls the singular "the buggy singular form".docs/framework/discovery.md—i18n_audienceandrequires_frameworkadded to the ModuleMeta section.Module count eleven → twelve across
index.md,modules/index.mdandframework/overview.md; branding was missing from the home-page list entirely.One non-docs file
templates/host/README.md.tplshippedalembic upgrade headinto every generated project, while that same project's Makefile and Dockerfile useheads. Plainly an oversight rather than a deliberate choice, so it's fixed here.Also worth a look
The deployment page now carries a warning that the default SQLite compose stack pins
SM_ENVIRONMENT=productionand a SQLite URL — which contradicts the production checklist directly above it. It's a local/demo stack, and moving to Postgres isn't a one-env-var swap because migration histories are dialect-frozen at autogenerate time.Verification
vitepress buildclean. NoteignoreDeadLinks: trueis set, so the build does not validate links — the cross-page anchors were checked against the generated HTML instead.Findings from a
/code-reviewpass are fixed in 1337b83, including one real error of mine: the magic-number check description overstated whatvalidate_imagedoes (it matches any allowed signature, not the declared type's).https://claude.ai/code/session_013W1MJ3T4FJEBcx1Xs9Tea2