Development

Before handing off a change#

1. Run the narrowest focused check while you iterate. Add regression coverage where behavior changed.
2. Update the affected guide or contract. Add user-visible changes to CHANGELOG.md.
3. Run the relevant formatter, inspect its diff, and rerun the focused check.
4. Run just ci.
5. For website and documentation changes, also run just check web and the production site build in Documentation website.

Documentation authoring#

Start every published Markdown file with YAML frontmatter:

---
title: Installation architecture
description: Manifest validation and installation boundaries
order: 20
audience: developers
toc: true
---

• Error codes are unique across documentation files. Register public codes in docs/help/errors/registry.json. Each code needs exactly one page at /help/errors/<lowercase-code>/.
• A top-level section with audience: developers appears under Contributors in the sidebar.
• A draft: true file fails the production build.
• Use README.md for a directory landing page. It maps to the directory route. Do not add index.md. Without a README, the build lists the visible children.
• Use relative Markdown links with the .md suffix. The build validates local targets and heading anchors. Update link fragments when you rename a heading. External links use only https: or mailto:.
• Use GitHub alert markers ([!NOTE], [!TIP], [!IMPORTANT], [!WARNING], [!CAUTION]) in blockquotes. The launcher shows them as labeled text, so meaning must not depend on color. Use one marker per point. Do not nest alerts.
• Put diagrams in fenced mermaid blocks with short labels. The launcher shows the block as text, so the prose must explain the contract.

Documentation website#

The SvelteKit site in web/ builds docs/ and CHANGELOG.md into the project website. It is dark-only and uses the tokens in web/src/lib/styles/arknights-client.css.

• The home page shows one official Arknights Global wallpaper from web/static/artwork/, the only artwork the repository bundles. Show it uncropped at 16:9. Credit the artist, Hypergryph, and Yostar beside it.
• --site-signal is the accent that WallpaperColorExtractor derives from that wallpaper. --site-signal-text is its AA-readable text variant. Update both together when the wallpaper changes.
• Use the signal only for the primary download action, active navigation, and focus. Use tinted fills. Keep secondary controls as quiet neutral capsules.

Use Node 24.14 or newer and the pnpm version in web/package.json. The website has no Vitest suite. Validate it with these commands:

just check web
cd web
BASE_PATH=/Arknights-MacOS-Client pnpm build

just check web runs Svelte, type, and Prettier checks. Run just format web to accept Prettier changes. The build fails unless frontmatter, routes, links, heading anchors, canonical and social URLs, accessibility metadata, and base-path URLs are valid. For a UI or Mermaid change, also check light, dark, desktop, and mobile pages with just dev web.

just ci does not run these checks. A documentation-only edit does not trigger Pages. Run Actions → Publish website → Run workflow from main, or let the release workflow call it. Other branches fail before deployment.