Marketing website maintenance¶
The public marketing site uses plain HTML, CSS and a small progressive-enhancement
script. English is the default; German is an explicit language choice. The combined
Pages build places these pages at the site root and the canonical English Markdown
handbook under handbook/. There is no application server, remote font service,
build-time frontend framework. Visitor statistics use one cookie-free Umami tag
that the build adds; see Visitor statistics. The appliance
dashboard is a separate application and is not changed by website updates.
Follow documentation maintenance for the combined build, CI and the one-time switch of the Pages source to GitHub Actions. The Azure Static Web App that hosts the site is defined in infrastructure/landingpage; GitHub Pages only redirects to it.
Sources and structure¶
| Source | Purpose |
|---|---|
| index.html | English product homepage |
| de.html | Equivalent German homepage; handbook links are marked English |
| editions.html, editionen.html | Licensing overview, eligibility and the actual request/activation workflow |
| site.css | Responsive navy/violet/cyan design from the October 2026 pitch mockup, system fonts for text, the local heading font, visible focus and reduced motion |
assets/fonts/ (bricolage-grotesque-qm-600-800.woff2, OFL.txt) |
Bricolage Grotesque (variable, weights 600–800) for headings on the landing pages, the legal pages and the handbook, with its SIL Open Font License text; see Heading font |
| site.js | Mobile navigation (also on handbook pages), keyboard-accessible dashboard screenshot tabs and the click-to-load product video; see Product video |
docs/overrides/ (main.html, partials/footer.html, partials/search.html) |
Material theme overrides: website header and footer on every handbook page and the accessible name of the search dialog; see Handbook pages |
assets/brand/ (logo.svg, brandmark.svg, core.svg) |
Magic Stick logo, brandmark and core symbol (SVG) from the pitch mockup |
assets/artwork/ (command-centre.jpg, two WebP backgrounds, four commander-tob-*.webp character illustrations and video-poster.webp) |
Hero illustration, two blurred section backgrounds, the Commander Tob guide character and the product-video poster; see Artwork provenance |
| assets/favicon.svg | Picture mark: brandmark on a light rounded tile |
| imprint.html, impressum.html | Imprint in English and German (Impressum), one text in two languages; see Legal pages |
| privacy.html, datenschutz.html | Privacy policy in English and German (Datenschutzerklärung), one text in two languages; see Legal pages |
| social.html, sozial.html | Imprint and privacy policy on one page, as the legal link of the social media profiles. The files hold no legal text; the build includes it. See Combined page for social media profiles |
The homepage follows the October 2026 pitch mockup. It moves from a full-width
hero illustration, the "Meet Commander Tob" welcome band and the light
product-video section (see Product video) through the
product section (intro, dashboard screenshot
switcher, application catalog cards), a "where would you like to start" choice
for individuals and teams, the four deployment environments with a GPU note, a
three-step first-use section, a team-pilot section with the licensing note, the
FAQ and a closing call to action. The guide character Commander Tob appears in
three places from the marketing concept of 16 October 2026: the welcome band
below the hero, the "Commander Tob explains" question picker at the top of the
FAQ and the closing call to action. The question picker answers three FAQ topics
(GPU, data flows, operational responsibility); the other questions stay in the
details accordion below it. The concept's video placeholders ("Video in
preparation") are not published: the poster is an illustration, not a video, until
actual videos exist. Readers without Kubernetes experience are the
audience: technical components (Kubernetes, Flux, Magic Stick Operator, LiteLLM,
KubeAI, engines, Keycloak/Envoy) are named in the FAQ and linked to the
architecture and compatibility references instead of being drawn on the page.
Every deployment environment links its installation guide; there are no
"documentation pending" placeholders from the mockup. The mockup's Typekit fonts
are not used; body text keeps the system font stack and only headings use the
local heading font.
The screenshot switcher and the Commander Tob question picker use the same
progressively enhanced tab pattern (data-tabs in site.js). The question picker
is a vertical tablist (aria-orientation="vertical", ArrowUp/ArrowDown) whose
selected question also replaces the poster caption (data-tab-caption). Without
JavaScript, all three answers show with their question as a heading.
The screenshot switcher is the progressively enhanced tab pattern: three
div panels (not figure, which may not carry the tabpanel role) with
reviewed captures are all readable without JavaScript, and site.js turns the
toolbar buttons into a keyboard-accessible tablist. "Enlarge
screenshot" is a plain link to the full image.
Keep both languages in sync when changing claims, links or sections. English pages
link the English legal pages, German pages the German ones. Language
switches are ordinary links, with no geolocation, language auto-redirect, cookie or
stored preference. Each page has a canonical URL, reciprocal English/German
hreflang links, an English x-default, descriptive metadata and an existing
hero illustration as the social preview. Homepage fragment IDs that other pages
link (#produktvideo, #produkt, #requirements, #hardware, #starten,
#teams, #lizenzen, #faq) remain available in both languages.
The source HTML links to canonical handbook Markdown. tools/docs.py converts
these to handbook/.../ links in the published artifact. Root repository files
such as LICENSE and SUPPORT.md use explicit public GitHub links; they are not
handbook pages. New marketing HTML must be included in MARKETING_PAGES and
excluded from MkDocs in mkdocs.yml. Do not collide with legacy redirect routes
from docs/migration.json (in particular licensing.html).
Handbook pages¶
The handbook is part of the website: every page that MkDocs Material renders
under handbook/ begins with the website header and ends with the website
footer, through the theme overrides in docs/overrides/.
main.htmlextends the Material base template. It places the website header (logo, the same navigation entries in the same order as the English landing page, GitHub, the EN/DE switch and the "Get started" button) above the Material header and loadssite.jsfrom the site root for the mobile menu. The Material row below is titled "Documentation" (site_name), keeps search and the section tabs and stays the sticky one; the website header scrolls away. The handbook uses Material's dark scheme only, like the website, without a light-mode toggle. Its GitHub button is hidden because the website header has one, and thehtmltitleblock keeps "Magic Stick Documentation" in browser titles. "Docs" is marked as the current entry. The handbook has no German version, so "DE" leads to the German homepage.partials/footer.htmlis a copy of the Material footer partial whose meta area (copyright, social links, "Made with Material for MkDocs") is replaced by the website footer, so a handbook page carries one footer: Material's previous/next page navigation followed by the logo, the licensing link and the English legal pages. Re-sync the navigation part whenmkdocs-materialis upgraded. The attribution of Material for MkDocs stays in THIRD_PARTY_NOTICES.md and in the generatedlicenses/documentation-build.txtof the site.partials/search.htmlis a copy of the Material search partial that only adds an accessible name to the search dialog; re-sync it as well.
The styles of the header and footer live in
handbook.css, scoped to .site-header and
.md-footer, because site.css also styles body text and headings and would
conflict with Material. The same file maps the website palette (navy canvas,
cyan links, the body font stack, the heading font) onto Material's variables so
that handbook pages read as the same site, and caps Material's grid at the
landing page's 1280px content width plus Material's inner gutters, so the
handbook does not run edge to edge on wide screens. Keep the colours, links, entries and
the 1080px menu breakpoint in step with site.css and the landing pages when the
header or footer changes. Links in the overrides point one level above the handbook
({{ base_url.rstrip('/') }}/..); the build's link check resolves them against
the combined artifact, and tests/test_website.py checks entries, order and the
single footer.
Product video¶
The section between the welcome band and the product section (#produktvideo,
from the marketing team's video preview of October 2026) presents the product
interview with Tobias Varlemann, published on the QualityMinds YouTube channel
(video wraCU3plXzo, in German; the English page says so). The preview's small
"Welcome aboard" block is not repeated because the welcome band above already
says it. The section continues the light band; the player is capped at 600px so
the copy and the poster share the row evenly.
Nothing from YouTube is loaded before the visitor acts: the source HTML holds
no iframe, the poster is a local image and the website tests keep it that
way. The poster is a plain link to the YouTube watch page, so the video stays
reachable without JavaScript. With JavaScript, site.js gives the link the
button role and, on click, replaces it with the youtube-nocookie.com embed
(extended privacy mode, autoplay, rel=0, interface language from the page
lang), moves focus into the player and announces the state through a visually
hidden live region. The "watch on YouTube" link below the player remains as the
fallback. The caption states that playing connects to YouTube and links the
privacy policy section #video, which describes YouTube embeds on the site in
general (extended privacy mode, click-to-load, consent per video) in both
languages; it covers further videos that follow the same pattern, so keep the
embed parameters, that section and the figcaption in step.
To change the video, update the data-video id, the two poster links and the
player titles in site.js in both languages, and replace the poster with a
reviewed image of the same dimensions.
Heading font¶
Headings (h1–h3) use Bricolage Grotesque from
docs/assets/fonts/bricolage-grotesque-qm-600-800.woff2, served from the site
itself; no remote font service is involved. The file is a variable font
(wght axis) subset by QualityMinds, and its SIL Open Font License 1.1 text
ships next to it as docs/assets/fonts/OFL.txt. Each stylesheet declares the
single @font-face with the weight range 600 800 and font-display: swap:
site.css, which the landing and legal pages share, references
assets/fonts/ relative to the site root,
handbook.css references ../assets/fonts/
because MkDocs copies docs/assets/ under handbook/. Body text, buttons and
navigation stay on the system font stack.
Heading rules follow the QualityMinds headline usage: weight 700, tight
line-height (.96 for h1/h2 on the landing pages) and -.015em letter
spacing. Weights outside 600–800 would be synthesized or fall back because
site.css disables font synthesis, so keep heading weights inside that range.
The committed file is a subset. Characters that it does not contain fall back
to the next font in the stack glyph by glyph, which is visible in a heading.
When replacing the file, check that it covers the characters that actual
headings use (at least Latin-1 letters including German umlauts, typographic
quotes and dashes) and keep the same file name or update both references
(site.css and handbook.css). Record the font's source
and license terms with the other collateral assets in
THIRD_PARTY_NOTICES.md.
Legal pages¶
The imprint and the privacy policy each exist as one legal text in two
languages: imprint.html with
impressum.html, and privacy.html with
datenschutz.html. Every landing page links the pair of its
own language. The handbook is English only, so the website footer in
docs/overrides/partials/footer.html links the English pair ("Imprint" and
"Privacy", as on the English landing page) from every handbook page; the EN/DE
switch on those pages leads to the German versions (see
Handbook pages). The pages carry the website header and
footer of their language and use site.css (the .legal rules) and site.js
like the landing pages; the EN/DE switch in the header leads to the other
language of the same text. They have reciprocal hreflang links and an English
x-default. The German pages keep the English section IDs so that deep links
such as #provider or #opt-out work in both languages. The only inline
script is the statistics opt-out of the privacy policy. The date of each text
is the <time> element in the "Last updated" line at the end of <main>.
Always change both languages of a pair together, in the same commit, and set the
same date in the <time datetime="…"> element of both versions.
tests/test_website.py (test_legal_pages_stay_in_sync_across_languages) fails
when the two versions drift apart: it compares the element structure, section
IDs, link targets (language-specific targets such as de.html/index.html are
treated as equal), every number in the text (legal references, addresses,
retention periods), the inline opt-out script and the update date. Translate
legal references with the same numbers (Article 6(1)(f) GDPR ↔
Art. 6 Abs. 1 lit. f DSGVO, Section 5 DDG ↔ § 5 DDG) and keep paragraph
boundaries equal. The check is structural; it does not replace a legal review of
the translation.
Combined page for social media profiles¶
Social media profiles need one link that leads to both the imprint and the
privacy policy. social.html (English, published as /social)
and sozial.html (German, /sozial) show both texts
below each other. They do not hold a second copy: each file contains the
header, footer, page heading and one placeholder per text,
<article data-legal-include="imprint.html">, and legal_includes in
tools/docs.py fills it at build time with the content of that page's <main>
and its inline script. Headings move one level down, below the page's own
<h1>. The introduction links the social media section of the privacy policy
as privacy.html#social-media; the build turns links to a section of an
included page into links within the combined page (#social-media). A change to a legal page therefore appears on the combined page with
the next build, including its "Last updated" date.
Without the build (a preview that serves docs/), the placeholders are plain
links to the separate pages. The section IDs of the imprint and the privacy
policy must stay unique between the two texts because they share one page;
test_social_pages_include_both_legal_texts_without_a_copy checks this and
that every paragraph of both texts is present.
Visitor statistics¶
mkdocs.yml holds an extra.umami block with the Umami script URL, the
website_id of this site and an optional domains list. When both values are
set, python tools/docs.py build adds one <script defer …> tag at the end of
<head> on every landing page and handbook page. The committed HTML sources,
docs/ previews, legacy redirect stubs and the tests stay free of remote scripts,
and an empty block builds the site without analytics. The build rejects a script
URL that is not public HTTPS and a website_id that is not a UUID.
The tag sets data-do-not-track, so browsers with Do Not Track enabled send
nothing, and data-exclude-search and data-exclude-hash, so query strings and
URL fragments are not recorded. Umami
itself sets no cookies and stores no identifier in the browser. The opt-out
button on privacy.html and
datenschutz.html sets umami.disabled in the
local storage of the current address, which the Umami script checks before
sending. domains restricts counting to the listed public hostnames so that
pull-request preview deployments do not appear in the statistics.
The privacy policy names the hosting providers, the Azure regions of the Umami
app and database in infrastructure/landingpage,
the collected fields, the monthly session identifier and the retention periods.
Umami has no retention setting of its own: the scheduled retention job in
umami.bicep deletes visitor records after retentionMonths, the period the
policy states. The Umami image is pinned by digest because the policy describes
what that version collects; review the policy before upgrading it.
Change those, the extra.umami block or the Umami tag attributes together with
privacy.html and datenschutz.html,
including the update date in both footers (see Legal pages).
The privacy policy also describes the project's social media profiles
(#social-media: Instagram, LinkedIn, TikTok, YouTube). Adding, removing or moving a
profile to another platform changes that section in both languages: provider
address, transfer safeguards, the joint-controller agreement for profile
statistics and the provider's privacy policy link.
Product and license claims¶
Only implemented functionality is presented as available. Use the current compatibility reference and canonical user guides to verify claims. A listed engine path is not universal device/model support. Sharing does not increase physical VRAM or imply hard per-model memory isolation. Realtime remains a separate experimental path; chat compatibility does not imply Realtime support.
Core functions include Resource Sharing and Private Mesh without a license file. Only Federated SSO requires Free Registered or Commercial activation. The technical edition does not decide legal eligibility. BSL production-use eligibility, third-party-service exclusions and the per-version MIT Change License remain defined by LICENSE and LICENSING.md.
The edition pages explain the existing unsigned request → private issuer review → signed upload → explicit activation workflow. They link to the published provider contact and license-management guide, not an invented checkout, price, trial, automatic activation service or support guarantee. The site overview does not change the license or replace legal review.
Product screenshots¶
The landing page reuses three unchanged, privacy-reviewed WebP captures from the owner-approved test appliance on 24 September 2026. The pitch mockup shipped a synthetic "Models" dashboard rendering; it is not used, because the website only shows actual, reviewed captures. The mockup's overview and application images are byte-identical to the reviewed captures below.
| Image | Website placement |
|---|---|
| dashboard-overview.webp | Overview tab: summary cards |
| models-memory.webp | Models tab (default): memory and slots |
| application-create.webp | Applications tab: unsubmitted application draft |
The capture manifest is the provenance and
integrity source. Captions identify the date and example nature of values; these
are not sizing recommendations or benchmarks. Images scale to the layout and keep
full-size links. Dimensions are declared to reserve space. Only the hero artwork
loads eagerly; screenshots load lazily. The remaining handbook captures stay under
assets/screenshots/ with their manifest.
No new live-appliance access, workload changes, image generation or pixel retouching is needed to rebuild this site. For refreshes, follow the handbook screenshot rules: default to read-only navigation and unsubmitted drafts, get specific approval before starting test workloads, review final pixels for private data, and update the manifest. Do not expose personal model names, credentials, internal addresses or browser chrome.
Sales decks, onepagers and infographic collateral live under AIMS-000 in Team-Innovation. They are not copied into the public Pages artifact.
Artwork provenance¶
The brand files under assets/brand/ and the artwork under assets/artwork/
were supplied with the Magic Stick pitch mockup (QualityMinds, October 2026).
They are illustrations and brand assets, not product evidence.
| File | Origin and handling |
|---|---|
brand/logo.svg, brand/brandmark.svg, brand/core.svg |
Illustrator exports from the mockup; editor IDs removed, <title> added. |
favicon.svg |
Picture mark (MagicStick_picture-mark.svg) supplied by QualityMinds, October 2026; XML declaration and editor IDs removed, <title> added. |
artwork/command-centre.jpg |
Hero background and social preview, 1670 × 942. Unchanged mockup file (Adobe Photoshop 27.10 export of 2 October 2026 with an Adobe Content Credentials/C2PA manifest, which a re-encode would strip). Decorative (alt=""). The screen in the scene shows third-party service marks (among them OpenAI and Kubernetes); review this before a wider campaign use and replace the file if brand clearance is not available. |
artwork/commander-tob-standing.webp (560 × 812), artwork/commander-tob-avatar.webp (200 × 247), artwork/commander-tob-working.webp (800 × 472), artwork/commander-tob-sitting.webp (900 × 659) |
Commander Tob character illustrations from the QualityMinds marketing concept of 16 October 2026 (C-Tob_standing_cut_01_single.png, Avatar_Commander_Tob_Frontal_Base.png, C-Tob_Fullcolor_sitting_V1.png); the working illustration follows the updated developer-kit asset tob-working.png of 20 October 2026. Transparent margins trimmed, scaled down and converted with Pillow at WebP quality 80; no other pixel changes. Decorative (alt=""), loaded lazily. Creator rights and the likeness release belong to the collateral review in THIRD_PARTY_NOTICES.md. |
artwork/side-workstation.webp, artwork/entrance.webp |
Blurred backgrounds of the first-use and closing sections, converted from the mockup PNGs (1672 × 941) with Pillow at WebP quality 78. Used as CSS backgrounds only. |
artwork/video-poster.webp |
Product-video poster, 960 × 540, from the marketing team's video preview (October 2026; Canva export). Converted from PNG with Pillow at WebP quality 84, pixels unchanged. Shows Tobias Varlemann and the German title "Was kann der Magic Stick."; decorative in the markup (alt="") because the link text names the video. Publication of the portrait and name is the marketing team's clearance, not a repository decision. |
The generation prompts of the artwork are not part of this repository; the mockup owner holds them. The previous generated artwork remains below for the record.
Search engines and AI crawlers¶
The build writes the crawler files to the site root; none of them is committed as generated output.
| Published file | Source |
|---|---|
robots.txt |
Generated by crawler_files in tools/docs.py: allows all crawlers and names the sitemap |
sitemap.xml |
Generated sitemap index of sitemap-pages.xml and the MkDocs handbook/sitemap.xml |
sitemap-pages.xml |
Generated from the canonical and hreflang links of every page in MARKETING_PAGES; a new landing page appears once it is listed there |
llms.txt |
docs/llms.txt, a curated llms.txt summary; relative handbook and landing-page links become absolute https://magic-stick.ai/ URLs |
BingSiteAuth.xml |
docs/BingSiteAuth.xml, the Bing Webmaster Tools ownership file, copied unchanged through VERIFICATION_FILES; keep it while the site is registered there |
Keep the llms.txt summary in step with the landing-page claims. docs.py check
fails when one of its relative links is not a landing page or a navigable
handbook page. The origin comes from site_url in mkdocs.yml.
Every page declares https://magic-stick.ai/ as its canonical URL, so search
engines consolidate other hostnames that serve the same content (for example a
second country domain) onto that address. hreflang only connects the English
and German versions; it does not mark alternative domains. A permanent HTTP
redirect of other hostnames to https://magic-stick.ai/ is configured outside
this repository (DNS or hosting), not in the static build. Search Console and
Bing Webmaster Tools registration and sitemap submission are account actions of
the site owner.
Preview and checks¶
From the repository root, after installing the documentation build dependencies:
.build/docs-venv/bin/python -m unittest tests.test_docs tests.test_website
.build/docs-venv/bin/python tools/docs.py build
node --check docs/site.js
python3 -m http.server 8765 --bind 127.0.0.1 --directory dist/docs-site
Open http://127.0.0.1:8765/. To preview only the unbuilt marketing layout, serve
docs/; Markdown links remain source links until the combined build resolves them.
Before publishing:
- Check the landing, licensing, legal and combined social pages and a nested handbook page at desktop, tablet and mobile widths, including 320px. Check actual document width as well as visual layout; the full-width hero illustration must not make the page scroll horizontally, and the handbook's website header must not either.
- Exercise every screenshot tab by mouse and ArrowLeft/ArrowRight/Home/End, and every Commander Tob question by mouse and ArrowUp/ArrowDown/Home/End. Confirm selected state, visible panel and focus agree. Check the mobile menu, link-close behavior and Escape-to-close with focus returned to its button.
- Check language switching, installation routes, licensing/contact, FAQ and full-size screenshots. Confirm the built page links into the handbook correctly.
- Disable JavaScript and reload: navigation and all three screenshot panels must remain readable, as must all three Commander Tob answers; FAQ uses native details/summary. Restore browser settings.
- Check missing images, browser errors, visible focus and reduced-motion behavior.
Accessibility conventions: every EN/DE switch link keeps its visible text at the
start of its
aria-label("EN, English"), body links in the handbook stay underlined, and an axe-core run (for example the axe DevTools extension) should report no WCAG A/AA violations on the landing, legal and handbook pages. - Run
git diff --checkand the public release scan below. A text scan does not replace screenshot privacy review.
gitleaks detect --source . --config .gitleaks.toml --no-git --redact
The documentation CI runs both test modules and the complete static build. The website tests cover language/metadata, source links, existing anchors, progressive markup, reviewed image dimensions, authoritative license links and build routing. They do not prove visual fit or interaction behavior: those need a browser.
Follow the public release checklist. After a push, confirm that the Azure Static Web Apps deployment succeeded for the exact commit and that published HTML/assets match it. GitHub Pages only needs the manual redirect workflow when the website address or its set of pages changes. No dashboard/container rollout is required for a website-only change.
Previous artwork provenance¶
The original abstract artwork ai-infrastructure.webp remains in the repository
but is no longer shown on the website.
ai-infrastructure.webp was generated with the built-in image-generation tool on
2026-09-09 and encoded as WebP (cwebp -q 85). Original dimensions: 1536 × 1024.
The generated image is an editorial illustration, not a product screenshot or
photograph. There are no third-party marks in the artwork.
Generation prompt:
Use case: stylized-concept. Asset type: original premium software website hero artwork, one image, landscape 3:2, crop-safe. Scene/backdrop: very light cool neutral grey studio cyclorama, close to #f2f5f0, almost white; continuous matte floor with subtle natural studio shadows. Primary request: abstract sculptural arrangement of exactly three small modular cubes suggesting coordinated local computing and open AI infrastructure. A balanced architectural composition combining brushed-silver aluminum and translucent dark forest-green glass, with one luminous acid-lime core visible within the glass cube. Two very restrained fine dark connector cables link the modules on the studio surface. Style/medium: sophisticated premium industrial editorial, photorealistic physically plausible 3D studio still life, tactile brushed metal grain, clean glass refraction, crisp forms with fine bevels. Composition/framing: medium-wide, slightly elevated three-quarter viewpoint, all three cubes centered in an elegant compact composition with generous breathing space around them, entire silhouettes visible, suitable as a contained artwork on the right half of a white marketing hero. Calm, confident, minimal. Lighting/mood: soft directional daylight with lovely grounded architectural shadows, delicate controlled highlights, gentle acid-lime light inside one core; restrained saturation otherwise. Constraints: this is an abstract software infrastructure metaphor, NOT a branded hardware product; no text, no labels, no logos, no UI, no watermark, no USB stick, no laptop, no robots, no brains, no grid pattern, no busy circuit board, no extra objects. Create exactly one original image.