Writing style and page kit

The site has three readers: partners and prospects (operators, game providers, affiliates, reward partners), investors and advisors, and the internal team. Public pages serve the first two and must be good enough to send to a prospect as-is.

Voice

• Plain, confident, specific. Second person for guides ("you send…"), third person for product pages ("PlayerPal links…").
• Lead with what the reader gets, then how. One idea per paragraph, 1–4 sentences. Prefer tables, steps and diagrams to long prose.
• No hype words (revolutionary, seamless, cutting-edge, best-in-class), no exclamation marks, no emoji in prose.
• British-neutral spelling as used in the repo (behaviour, authorisation is fine either way; be consistent within a page). Use the glossary terms: Player, Account, Operator, Game provider, Affiliate, Reward partner, Link, Unlink, Audience, Alias, Activity, Points.
• Never invent product behaviour, pricing, commercial terms, SLAs, legal conclusions, certifications, customer names or numbers. If the repo does not say it, leave it out or say "contact PlayerPal" / "not yet decided".

Status labels

Readers see three labels. Front matter keeps the precise value:

Front matter status	Reader label	Meaning
implemented	Available	Built and tested in the platform
in-progress	In development	Being built; behaviour may change. Add demo: true if it exists only as demo code
proposed	Planned	Designed or decided, not built yet

Inline: <Status kind="in-progress" />. On a page that mixes statuses, give each section its own <Status … /> right under the heading. A mockup or demo UI never makes something Available.

Public pages

Front matter audience: public. In addition to the rules above:

1. No links into the repository (source files, ADRs, internal pages). The public build fails on them. Link only to other public pages (relative .mdx paths) or to the API reference at /api/partner.
2. Keep evidence in MDX comments, invisible to readers but reviewable: {/* evidence: services/api/src/ingest/ingest.controller.ts, ADR 0006 */} under each claim-heavy section. HTML comments (<!-- -->) do not work in MDX.
3. No internals: no hostnames, IPs, cloud vendors, cluster or database details, environment variable names, seeded or demo IDs, internal team process, known bugs or code-level discrepancies. Describe behaviour and guarantees, not implementation. Known gaps that affect partners are stated as product status ("In development", "Planned"), not as bugs.
4. Examples use placeholders (pp_kid_XXXX, <your-secret>) and paths only (POST /v1/ingest). If a full URL is unavoidable, use https://<playerpal-api-host>. Never a real or made-up hostname.

Page kit (MDX)

New pages are .mdx. These components are available on every page without imports:

<CardGrid cols={3}>
  <Card title="Link players" href="./linking-players.mdx" eyebrow="Guide">
    Connect a casino account to PlayerPal without sharing personal data.
  </Card>
</CardGrid>

<Steps>
  <Step title="Get credentials">…</Step>
  <Step title="Sign a request">…</Step>
</Steps>

<Tabs groupId="lang">
  <TabItem value="curl" label="curl">…code block…</TabItem>
  <TabItem value="node" label="Node.js">…code block…</TabItem>
</Tabs>

<Status kind="implemented" />

Admonitions: :::note, :::tip, :::info, :::warning, :::danger, with an optional title: :::info[In development]. Diagrams: ```mermaid fences (flowchart, sequenceDiagram, stateDiagram-v2).

MDX pitfalls: a bare < or { in prose breaks the build. Write <, use backticks (`a < b`), or put it in a code block. Leave a blank line before and after JSX blocks and inside <TabItem> around code fences.

Developer guide kit

Developer guides use a two-column layout: prose on the left, a sticky code column on the right. Add wide: true and hide_table_of_contents: true to the front matter, then:

<GuideMeta time="About 15 minutes" audience="Game providers and operators"
  outcomes={['Sign requests', 'Send a batch']} needs={['A key ID and secret']} />

<Walkthrough>
<WalkStep n={1} title="Send your first batch">

<Endpoint op="ingestSubmit" />

Prose, lists and tables for this step.

<Params op="ingestSubmit" in="body" only={['schema', 'batch_id']} />

<Checkpoint>What the reader should see now.</Checkpoint>

<WalkCode>

<Sample region="send-batch" title="POST /v1/ingest" />

<Example title="Response" status="202">{`{ "replayed": false }`}</Example>

</WalkCode>
</WalkStep>
</Walkthrough>

• Endpoint and Params read the generated partner OpenAPI document by operationId, so they always match the code. Params takes in="body" | "query" | "path" | "header" | "response".
• Sample shows a named region (docs:start <name> … docs:end <name>) of the files in docs-site/samples/signing/ in six languages, with a language choice remembered across the site. Those files run against the HMAC test vectors in CI (npm run check:samples), so change code there, never inline.
• Example is for static payloads such as responses and errors; pass the text as a template literal so MDX does not parse it.
• Explainer is a short animated walkthrough (scenes with play, pause and scrub). Pick one with id: <Explainer id="linking" />. The ids are in docs-site/src/components/explainer/registry.ts. Each explainer is hand-built in explainers/, so its values must match the sources its page cites; the signing values live in data.ts and must match the test vectors. Use one per concept, near the top of its page, and give it an evidence comment like any other claim. Add scenes in the explainer's file. Each scene is a pure function of its progress, so keep it that way.

Page template

---
title: Link players                 # short, task-shaped
description: One sentence that works as a search snippet.
sidebar_label: Linking players      # optional
status: implemented
audience: public
verified: <commit>
---

# Link players

One-paragraph summary: what this does for the reader and when to use it.

## How it works        (diagram or steps)
## Before you start    (prerequisites)
## Step by step / Reference
## Errors and edge cases
## Related             (2–4 cards or links)

Aim for 80–220 lines. Every public page ends with a short Related section.