Skip to content

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.html extends 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 loads site.js from 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 the htmltitle block 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.html is 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 when mkdocs-material is upgraded. The attribution of Material for MkDocs stays in THIRD_PARTY_NOTICES.md and in the generated licenses/documentation-build.txt of the site.
  • partials/search.html is 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.

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:

  1. 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.
  2. 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.
  3. Check language switching, installation routes, licensing/contact, FAQ and full-size screenshots. Confirm the built page links into the handbook correctly.
  4. 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.
  5. 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.
  6. Run git diff --check and 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.