---
title: Operations and runbooks
description: 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](https://github.com/blinqx-hq/basenet-rebuild-poc/blob/main/docs/runbooks/local-dev.md) | Docker-backed services, demo tenant, app ports, logs, reset and smoke checks |
| Isolate concurrent branch stacks | [Parallel worktrees](https://github.com/blinqx-hq/basenet-rebuild-poc/blob/main/docs/runbooks/parallel-worktrees.md) | `pnpm worktree:env`, per-worktree ports/database names, safe teardown |
| Boot migrated Basenet-shaped tenant data | [Real-tenant fixture](https://github.com/blinqx-hq/basenet-rebuild-poc/blob/main/docs/runbooks/real-tenant-fixture.md) | `pnpm dev:tenant`, fixture purity and expected counts |
| Acquire and use provider test credentials | [Vendor sandbox](https://github.com/blinqx-hq/basenet-rebuild-poc/blob/main/docs/runbooks/vendor-sandbox.md) | 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](https://github.com/blinqx-hq/basenet-rebuild-poc/blob/main/docs/runbooks/tenant-provision.md) | Database, realm, storage, search, seed, residency and activation steps |
| Operate realms and staff login | [Identity](https://github.com/blinqx-hq/basenet-rebuild-poc/blob/main/docs/runbooks/identity.md) | Tenant realm/client setup, admin and staff login diagnosis |
| Rotate migrated credentials | [Credential rotation](https://github.com/blinqx-hq/basenet-rebuild-poc/blob/main/docs/runbooks/credential-rotation-bli-218.md) | 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](https://github.com/blinqx-hq/basenet-rebuild-poc/blob/main/docs/runbooks/m365-setup.md) | Entra app, delegated OAuth grants, callback and doctor checks |
| Connect matter document sync | [Microsoft 365 documents](https://github.com/blinqx-hq/basenet-rebuild-poc/blob/main/docs/runbooks/m365-documents-setup.md) | Separate documents app registration, permissions and folder-sync validation |
| Configure Outlook add-in SSO | [Outlook add-in SSO](https://github.com/blinqx-hq/basenet-rebuild-poc/blob/main/docs/runbooks/outlook-addin-sso.md) | Entra administrator checklist and Office SSO/OBO path |
| Configure Word add-in SSO | [Word add-in SSO](https://github.com/blinqx-hq/basenet-rebuild-poc/blob/main/docs/runbooks/word-addin-sso.md) | The Word-specific half: a second Application ID URI on the shared Entra registration, and manifest generation |
| Configure Office preview/edit | [WOPI setup](https://github.com/blinqx-hq/basenet-rebuild-poc/blob/main/docs/runbooks/wopi-setup.md) | 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](https://github.com/blinqx-hq/basenet-rebuild-poc/blob/main/docs/runbooks/docs-surfaces.md) | Source/artifact flow and local/public endpoints |
| Update NL/EN customer manuals | [Handleiding refresh](https://github.com/blinqx-hq/basenet-rebuild-poc/blob/main/docs/runbooks/handleiding-update.md) | Drift inventory, page pairing, screenshots/video and content checks |
| Build/deploy partner + developer docs | [Partner docs Pages](https://github.com/blinqx-hq/basenet-rebuild-poc/blob/main/docs/runbooks/partner-docs-pages.md) | Blume build, GitHub Pages and OpenAPI symlink verification |
| Refresh generated repository wiki | [OpenWiki](https://github.com/blinqx-hq/basenet-rebuild-poc/blob/main/docs/runbooks/openwiki.md) | 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](https://github.com/blinqx-hq/basenet-rebuild-poc/blob/main/docs/runbooks/deploy.md) | Images, migrations, Helm/Cloud Foundry release and smoke checks |
| Cut over from legacy Basenet | [Cutover](https://github.com/blinqx-hq/basenet-rebuild-poc/blob/main/docs/runbooks/cutover.md) | Freeze, extract/load, verification, switch and rollback decision points |
| Respond to a production incident | [Incident response](https://github.com/blinqx-hq/basenet-rebuild-poc/blob/main/docs/runbooks/incident.md) | Triage, containment, communication, recovery and follow-up |
| Restore tenant/control-plane data | [Backup and restore](https://github.com/blinqx-hq/basenet-rebuild-poc/blob/main/docs/runbooks/restore.md) | 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

```bash
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](/developers/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`

See also: [Setup and checks](/developers/setup) · [Tenant isolation](/developers/tenant-isolation) · [Public API and docs](/developers/public-api)