Operations and runbooks

Purpose-based landing page for every current operational runbook in the repository.

Use this page to choose a runbook. The linked files under docs/runbooks/ are the canonical procedures; this page explains when each one applies and which verification signal closes the operation.

Development and test environments

Need	Runbook	Use it for
Boot or troubleshoot the local stack	Local development	Docker-backed services, demo tenant, app ports, logs, reset and smoke checks
Isolate concurrent branch stacks	Parallel worktrees	`pnpm worktree:env`, per-worktree ports/database names, safe teardown
Boot migrated Basenet-shaped tenant data	Real-tenant fixture	`pnpm dev:tenant`, fixture purity and expected counts
Acquire and use provider test credentials	Vendor sandbox	Named sandbox variables, ownership, evidence, and clean skip behavior

Stop condition: the intended isolated environment is reachable, its documented smoke check passes, and no duplicate server/container remains running.

Tenant and identity lifecycle

Need	Runbook	Use it for
Create a tenant	Tenant provisioning	Database, realm, storage, search, seed, residency and activation steps
Operate realms and staff login	Identity	Tenant realm/client setup, admin and staff login diagnosis
Rotate migrated credentials	Credential rotation	Rotation sequence, tenant-scoped resource eviction and migration controls

Stop condition: the control plane reports the expected tenant state, identity checks succeed for the intended realm, and no credential value appears in logs or command arguments.

Microsoft 365 and Office

Need	Runbook	Use it for
Connect delegated user mailboxes	Microsoft 365 delegated mail	Entra app, delegated OAuth grants, callback and doctor checks
Connect matter document sync	Microsoft 365 documents	Separate documents app registration, permissions and folder-sync validation
Configure Outlook add-in SSO	Outlook add-in SSO	Entra administrator checklist and Office SSO/OBO path
Configure Word add-in SSO	Word add-in SSO	The Word-specific half: a second Application ID URI on the shared Entra registration, and manifest generation
Configure Office preview/edit	WOPI setup	WOPI discovery, allowlists, proof keys and host integration

Stop condition: the exact delegated or app-only flow named by the runbook succeeds against its intended environment; a mock success is never reported as live Graph/WOPI proof.

Documentation surfaces

Need	Runbook	Use it for
Understand OpenWiki, Blume and Scalar ownership	Docs surfaces	Source/artifact flow and local/public endpoints
Update NL/EN customer manuals	Handleiding refresh	Drift inventory, page pairing, screenshots/video and content checks
Build/deploy partner + developer docs	Partner docs Pages	Blume build, GitHub Pages and OpenAPI symlink verification
Refresh generated repository wiki	OpenWiki	Safe heap/exclude wrapper; never bare `openwiki --update`

Stop condition: the relevant docs build/check is green, internal links resolve, and user-visible instructions include inspected visual evidence when required.

Deterministic docs gates

Two scripts turn drift in the customer manual into machine-checkable findings instead of relying on someone re-reading every page:

Label-currency ratchet — scripts/handleiding-check.mjs cross-checks every **Bold** on-screen label quoted in content/handleiding/ and content/guides/ against the i18n catalogs. Unmatched labels found on a normal run are warnings; passing --strict-labels (as CI does) turns them into failures, but only for labels not already listed in scripts/handleiding-labels-baseline.json. That baseline is a ratchet, not a suppression list — it freezes today’s known noise so the check is useful from day one instead of failing on a pre-existing 500-line backlog, and it shrinks over time via --update-baseline as entries get fixed or reclassified. It never grows silently: a genuinely new mismatched label fails CI even with the baseline present.
Capture manifest — scripts/write-capture-manifest.mjs runs at the end of pnpm docs:capture / docs:capture:guides and stamps apps/docs/public/media/.capture-manifest.json with the capture timestamp and the apps/web commit SHA the screenshots/video were taken against. handleiding-check.mjs reads that manifest to warn (not fail) when apps/web/src has changed since the manifest’s SHA — a cheap signal that the manual’s screenshots may now be stale, without asserting pixel-level drift the script can’t actually detect.

Both checks run inside pnpm docs:handleiding-check; CI additionally passes --strict-labels.

Deploy, continuity, and incident response

Need	Runbook	Use it for
Deploy application components	Deploy	Images, migrations, Helm/Cloud Foundry release and smoke checks
Cut over from legacy Basenet	Cutover	Freeze, extract/load, verification, switch and rollback decision points
Respond to a production incident	Incident response	Triage, containment, communication, recovery and follow-up
Restore tenant/control-plane data	Backup and restore	Restore procedure, integrity checks and automated restore verification

Stop condition: the runbook’s post-operation health and data-integrity checks pass on the exact deployed version/tenant; otherwise follow its rollback or escalation boundary.

Cross-cutting operational invariants

Resolve the exact environment, tenant, commit/image, and migration state before mutation.
Production schema changes run deliberately; deployed workers honor SKIP_MIGRATE=1 and do not advance schemas at boot.
Never place passwords or service tokens in argv, docs, screenshots, or logs.
Provider evidence names the tier: mock, sandbox, or real.
Tenant routing and current active status are rechecked at request/job execution time.
A runbook is incomplete until its verification and cleanup/rollback steps have been evaluated.

Focused validation

pnpm --filter @blinqx/docs test
pnpm --filter @blinqx/docs build
pnpm docs:handleiding-check
pnpm docs:openwiki -- --preflight

Choose the narrower check for the surface changed; run the docs build before publishing this site. See Testing for repository-wide gates.

Source anchors

Canonical procedures: docs/runbooks/*.md (all current files are surfaced above)
Docs scripts: package.json, apps/docs/package.json, scripts/handleiding-check.mjs, scripts/openwiki-update.mjs
Runtime composition: scripts/dev.mjs, apps/workers/src/main.ts, apps/control-plane/src/cli.ts