Maintainers

How Pixel is built, secured and run. These pages are the same files as docs/ in the repository, so they change in the same pull request as the code they describe.

New to running Pixel?

Read the operations runbook first. It covers access lists, moderation, deploys, secrets, incidents and privacy requests.

Start here

Page	What it covers
Architecture	The design, the phase 1 scope, configuration, deployment and CI/CD pipelines.
Identity and access	Tiers, capabilities and how every command is authorised. Read it before touching anything auth-related.
Infrastructure	How Azure, GitHub, Discord, Home Assistant and Sentry fit together.
Home Assistant	Setup on a test instance, the threat model and revoking the token.
Operations runbook	Day-to-day tasks and what to do when something breaks.
Privacy notice	What Pixel stores about people, why, where and for how long, and how to ask for a copy or deletion.
Hiding commands in Discord	Showing admin commands only to admins.

Decisions

Architecture decision records, newest last.

ADR	Decision
0001	TypeScript, ports-and-adapters core, interactive vs publisher adapters.
0002	Phase 1 tiers from gitignored YAML files; admins in a separate file; fail closed.
0003	No database: access, schedules and planned linking are files.
0004	Azure Container Apps, single replica; GHCR; dev + prod.
0005	Sentry for errors, pino to stdout, a rotating file and Sentry Logs.
0008	Terraform bootstrap: remote state and GitHub OIDC.
0009	Container Apps module and the dev environment.
0010	Temporary GHCR CD: local dev, main publishes only.
0011	Home Assistant: official client, allow-list, no inbound webhooks.
0012	Prod environment and approved CD.
0013	Releases cut versions and promote prod.
0014	Releases register prod slash commands.
0015	One manifest lists every Key Vault secret.
0016	just pull / just push (and secrets-pull / secrets-push) sync tfvars and app secrets between Key Vault and the laptop.
0017	Only the sync tool writes app secrets; Terraform writes just the infra group.

Working on the site

The site lives in docs/ and is built with VitePress. It has its own package.json and lockfile, so nothing it needs reaches the bot's image.

just docs-install   # once
just docs-dev       # http://localhost:5173 with hot reload
just docs-build     # the static site, in docs/.vitepress/dist

• The guide and command pages are written for people using Pixel. Keep them in the design system's voice: plain, friendly, exact, and no emoji.
• A new maintainer doc in docs/ needs a line in MAINTAINER_DOCS and the sidebar in docs/.vitepress/config.ts. A new ADR in docs/adr/ only needs the sidebar.
• Links to files outside docs/ (../src/…, ../justfile) are turned into links to GitHub when the site is built.
• Publishing: the Docs site workflow builds the site on every pull request that touches docs/. GitHub Pages is published as part of a Release (or by running Docs site by hand). A dead link fails the build.
• The theme is in docs/.vitepress/theme/. Its colours, type and spacing come from the Pixel design system: change them there first, then here.