Wahy documentation

Reference documentation for the Wahy platform, kept docs-as-code: the Markdown source lives in this repo and is updated in the same PR as the code that changes behavior (see ../CONTRIBUTING.md). The same source renders at docs.wahylabs.com (in-app, via a remark/rehype CommonMark pipeline). Docs are split into public user-guides and superadmin-gated engineering/ops references.

Maintenance rule: every claim here must be traceable to a file:line / route / env / migration that exists. When a doc and the code disagree, the code wins — correct the doc. The CI docs drift-guard (npm run verify:docs-drift) enforces that docs don't reference removed env vars / routes / files / migrations.

Map

On docs.wahylabs.com, the User guides are public/indexable; the engineering, ops, and testing references below require a signed-in superadmin (they render 404 to anyone else). Their titles are listed here for orientation; the sidebar shows only what the current viewer can open.

User guides (public)

• overview.md — what Wahy is, the tenancy model, the four surfaces, and a glossary.
• guide-public-site.md — the public tenant site: blocks/themes, booking, i18n, SEO.
• guide-admin.md — the tenant admin CMS: every surface, how an owner uses it.
• guide-marketing-signup.md — the marketing site + public signup flow.

Platform reference (engineering · superadmin-gated)

• architecture.md — the technical map: request lifecycle, modules/entitlements, billing, theming/editor, i18n, storage, jobs, SEO.
• guide-control-plane.md — superadmin control-plane operator guide (lifecycle, impersonation, packages, refunds, health).
• data-layer.md — Postgres + Drizzle + RLS (the #1-risk area), tenancy roles.
• tenancy.md — subdomain tenancy model, proxy resolution, control-plane host.
• auth.md — Auth.js v5, memberships, member-only login gate, superadmin.
• whatsapp-integration.md — WhatsApp Cloud API inbound webhook + CRM ingestion.
• whatsapp-live-replay.md — owner-run turn-by-turn verification of the bot-reliability fixes against a real number (the one thing mocks can't cover).
• specs/vertical-foundations-spec.md — multi-vertical platform reference.

Operations & deployment (superadmin-gated)

• guide-ops.md — start here: the operations & maintenance runbook hub (topology, deploy/rollback, secrets, monitoring, backups, incident response).
• config-reference.md — every environment variable: purpose, where set, default, fail-open vs fail-closed.
• operations-guide.md — day-to-day operations.
• production-deploy.md — self-hosted GCP Compute + Caddy prod deploy.
• cd-pipeline.md — GHCR images, branch→env CD, release flow.
• ci-runner-action-cache.md — why CI jobs stop fetching actions from codeload.github.com (R296): the sha-pinning + runner action-archive cache, how to apply and verify it.
• provisioning-runbook.md — tenant provisioning (TS + break-glass shell).
• pgdata-migration-runbook.md — moving VM1's live Postgres onto its provisioned /mnt/pgdata disk (R105, reviewed but NOT executed).
• monitoring.md — Prometheus / Grafana / Loki / Alertmanager / GlitchTip.
• hardening.md — edge hardening.
• scaling-playbook.md — threshold→action scaling table.
• vm-disk-cleanup.md — VM Docker-image retention systemd timer.
• aws-agent-rules.md — working rules for AI agents touching AWS (from the AWS Agent Toolkit), plus how they sit against this repo's Terraform and SOPS conventions.
• launch-checklist.md — content & media launch checklist.

Local dev & testing (superadmin-gated)

• local-docker.md — the local Docker Compose stack.
• testing.md — test layers (unit / test:pg RLS-isolation / E2E / visual) + how to run.
• testing-coverage-gaps.md — living cross-tenant isolation coverage map.
• qa/test-plan.md — comprehensive QA test plan: a surface-by-surface, feature-by-feature test-case matrix with automation targets and honest coverage status, plus the prioritized follow-up backlog.

Process

• project-management.md — how work is planned and tracked.
• history/ — archived completed-stage narrative, dated audits, and superseded plans (kept for reference, not living docs).

Keeping this index current

This file is the source-of-truth navigation for the docs.wahylabs.com site and the docs/ folder. When you add a doc, add it here and to lib/docs/manifest.ts (which sets its URL slug + public/internal access) in the same PR — the drift-guard keeps the links honest, but placement and access are yours to set.