Skip to main content
This page defines where docs belong, who owns updates, and how automated checks detect drift between code and documentation.

​
Purpose

Use this policy to keep docs aligned with product behavior and architecture changes while reducing manual review overhead.

​
Source-of-truth locations

​
Placement rules

​
Feature changes

When implementation changes user behavior, add or update docs in:
  • docs/features/** for end-user functionality
  • docs/organization/** for org/team/role workflows

​
Architecture and development changes

When implementation changes setup, runtime behavior, infrastructure, workflows, or internal architecture, add or update docs in:
  • docs/engineering/backend/**
  • docs/engineering/frontend/**
  • docs/engineering/mobile/**
  • docs/engineering/infrastructure/**
  • docs/engineering/development/**

​
Docs coverage manifest

The file docs/engineering/development/docs-coverage-manifest.json maps high-impact code areas to expected docs paths. Automation uses this map to:
  • flag code changes without matching docs updates
  • identify likely docs targets for a change
  • produce weekly drift reports

​
PR requirements

PRs that change high-impact code should include:
  • at least one docs update in mapped docs paths, or
  • an explicit exemption label such as no-doc-impact

​
Changelog requirements

docs/changelog.mdx is the public release stream for Soundcheck customers and org admins.
  • PRs must include a ## Changelog section. Use customer-facing bullets, or - N/A when nothing a customer would notice.
  • Docs-policy accepts that PR section without editing docs/changelog.mdx. Edit the public file only for product behavior a customer would see.
  • Do not add ### Internal headings, [Internal] bullets, bullets under existing Internal sections, or seed / emulator / CI / agent-skill notes to docs/changelog.mdx. Put those in the PR Description, Additional Notes, or docs/engineering/**.
  • Protected branch workflows can sync merged PR titles into changelog markers. That is not a license to paste internal PR notes into the public file.

​
Weekly audit

A scheduled report-only sweep audits:
  • code-to-doc drift based on the manifest
  • stale or missing docs references in .cursor/rules and .agents/skills
  • merged PR coverage in docs/changelog.mdx

​
Slack communication

Docs and changelog updates are communicated to Slack via CI workflows:
  • scheduled digest: .github/workflows/slack-changelog.yml
  • push-based docs notifications: .github/workflows/docs-slack-notify.yml

​
Slack setup checklist

  1. Create a Slack incoming webhook for docs updates and store it as SLACK_DOCS_WEBHOOK in GitHub Actions secrets.
  2. Create a Slack incoming webhook for scheduled changelog digests and store it as SLACK_CHANGELOG_WEBHOOK.
  3. Run Docs Slack Notify manually once to verify docs notifications.
  4. Run Daily Slack Changelog manually with days_back=1 to verify digest delivery.

​
Maintenance

When new code areas are added or moved:
  1. Update docs-coverage-manifest.json
  2. Add or adjust docs pages in docs/**
  3. Update docs/docs.json navigation when new docs pages are introduced

​
Archived operator release notes

Moved from the public changelog on September 15, 2026. Dates and recorded implementation context are retained as historical notes, not current operating instructions. Original implementation wording is retained below when the public entry keeps a shorter customer-facing summary.

​
Sep 1, 2026

​
MCP

  • Public MCP hostnames now share the api-events Cloud Run and ALB (mcp.soundchecklive.io, qa-mcp.soundchecklive.io, dev-mcp.soundchecklive.io). Those hosts only serve /mcp, /public/mcp, and /.well-known/*. Protected Resource Metadata resource is that hostname’s /mcp path. At the time, connect URLs waited on DNS and TLS (ENG-613; since Done, see Sep 4).

​
Aug 31, 2026

  • Web Playwright CI is faster: setup signs in through Clerk’s testing API instead of the hosted form, shards pack specs by recorded duration instead of test count, and a failed login no longer burns two extra retries. Auth-required pages wait for a Clerk token before fetching. Org Activity seeds its capture row through the venue write API because PR CI turns the venues page off.
  • Activity filters no longer leave the previous page of rows on screen. Changing category hides the last filter’s rows until the matching page arrives. The members e2e opens a removable member, not the owner (whose menu is only View in org activity).
  • Org Activity category, action, and actor filters apply on the first click. A second cmdk select (keyboard Enter) no longer undoes the filter while the URL still shows it.
  • Filtering organization Activity by category, action, actor, or source now actually narrows the table. The web client sends array query params as categories[]=; the API only read categories, so the chip updated while the feed stayed unfiltered.
  • Authenticated web fetches no longer fire before the Clerk token getter is installed, and a 401 is not retried or logged as a hard auth failure when the request never had a bearer token.

​
MCP

  • Member MCP OAuth discovery now lists Clerk on hosted API hosts even when OAUTH_ISSUER was not mounted, and serves RFC 8414 authorization-server metadata plus the path-appended protected-resource document so third-party agents can find Dynamic Client Registration.

​
Aug 30, 2026

​
MCP

  • Hosted public MCP tools existed on the API host (org lookup, positions, booking request, sponsorship request). At the time, connect URLs waited on mcp.soundchecklive.io DNS (ENG-613; since Done, see Sep 4).
  • Member MCP on the API host returned 401 without auth and PRM listed Clerk; customer OAuth advertise waited on the same DNS work (since Done, see Sep 4).

​
Aug 27, 2026

  • Dev and QA no longer keep the retired Azure API App Service. Postgres and blob storage in those environments stay. Production still has the Azure API App Service.

​
Aug 21, 2026

  • Formula B Instant-writer freeze is dump now() 2026-08-20 23:19:32 UTC. Applied Formula B SQL still uses the < 2026-09-15 upper bound; do not rewrite applied migrations.
  • Mobile OTA stamps Soundcheck-Revision from the checked-out HEAD, including a later fingerprint version-bump commit.

​
Aug 20, 2026

​
Gigs

  • Existing gig, offer, and schedule call times convert once from the 2026-08-20 production snapshot, including both start and end of a window. Re-running that conversion does not shift times again.

​
Aug 17, 2026

  • New api-events Prisma migrations must replay safely after apply. Older folders are grandfathered.
  • Raw api-events LIKE / ILIKE queries, including new Prisma migrations, now require ESCAPE and escaped search patterns so _ and % are literals unless intended as wildcards. Older migration folders are grandfathered.

​
Gigs

  • Gig call times with a venue timezone are written as UTC Instants. Flex-imported gigs keep the quote Instant and gain a venue timezone so display can project. Remaining wall-clock digits, including schedule item call times, convert only after Formula B applies.

​
Aug 14, 2026

  • Basic Auth removed. api-events accepts Clerk session JWTs only. CI and e2e mint tokens from the local clerk-emulator. ENABLE_BASIC_AUTH=true fails closed. The unused staff admin console (/api/v1/admin/**) 404s every request; STAFF_ACTOR_ALLOWLIST and X-Staff-Actor are gone.
  • Removed the informational Factory QA workflow (qa.yml) and playbooks (.factory/skills/qa*). Browser, API, and mobile coverage stay on Playwright, encore-e2e, and Maestro.
  • E2E Quick start uses npm run dev:emulator, prefixes DATABASE_URL on migrate/seed (dev:infra does not export it), and runs focused suites through npm run test:api-events so Clerk/API/DB env match the PowerShell runner. The JS getConfig() fallback is the same shared :5433 URL; isolated CI still overrides to :5434. Session JWTs remint before expiry on long Vitest runs.

​
May 10, 2026

​
Unified engagement inbox, operator data importer, and sidebar overhaul

  • Page layouts normalized to a shared PageHeader for consistent titles, descriptions, and action slots.

​
Engagement service, calendar handoff, and operator import endpoints

  • Accepting an invitation or crew offer now calls CalendarService.AddAttendeeToEvent with responseStatus=accepted, so the user’s Google Calendar RSVP follows automatically.
  • Added operator import endpoints under /v1/organizations/{orgId}/imports/* (create, list, parse, map, preview, commit, catalog). Optional AI-assisted mapping (opt-in via IMPORT_AI_MAPPING_ENABLED) scrubs PII before any model call.
  • Added partial unique indexes on Invitation(eventId, email) and Invitation(eventId, phoneNumber) so invitation upserts are idempotent across retries.

​
May 8, 2026

​
Analytics, sync, and operational hardening

  • Configured the PostHog proxy and enriched user, organization, role, and group analytics identification.
  • Continued OpenAPI sync, web coverage expansion, and CI stability improvements around the new CRM, availability, and payment workflows.

​
Mar 16, 2026

​
Financial and roster workflow refinements

  • Implemented Stripe destination-charge payout architecture and payout funding flow work for member payments.

​
Routing and onboarding stability

  • Improved onboarding and authentication E2E coverage for cached sessions and redirect timer teardown.

​
Audit and finance reliability updates

  • Hardened workflow and user event parsing paths to reduce edge-case failures and reduce noisy update payload handling.

​
CI/CD and operational hardening

  • Hardened API deployment and backend workflow guards for safer concurrency and PR handoff safety.
  • Stabilized Docker/devcontainer startup tooling and fixed pipeline failures in docs, migration, and API job chaining.
  • Continued maintenance of changelog/docs tooling, including broken-link and sync workflow cleanup for release-note automation.

​
Documentation and platform reference updates

  • Cleaned up docs/changelog automation references and updated documentation workflows to reduce CI drift.

​
Feb 20, 2026

​
Profile editing & UI improvements

  • Added Edit General Information screen with Figma parity (ENG-65)
  • Fixed null-user loading state and KeyboardAvoidingView indentation

​
Feb 19, 2026

​
Authentication & onboarding fixes

  • Fixed gig invite handler and position_name field mismatch

​
Feb 18, 2026

​
Security & middleware hardening

  • Implemented CORS origin allowlist and fail-closed behavior
  • Added Twilio webhook signature verification
  • Tightened client IP handling in middleware
  • Added dynamic rate limiting configuration
  • Implemented fail-closed behavior for ENVIRONMENT variable
  • Added security observability for auth/authorization failures
  • Removed legacy basic auth and closed bypass vulnerabilities

​
Feb 17, 2026

​
CI/CD & workflow improvements

  • Updated CI workflows with workflow_run triggers and success guards
  • Added schema drift detection and health checks
  • Added baseline data seeding and handler generation to CI
  • Consolidated docs automation workflows
  • Added Slack changelog digest with Block Kit formatting

​
Feb 15, 2026

​
Repository & handler improvements

  • Implemented Prisma-based subscription repository
  • Standardized error handling for “Not Found” cases
  • Improved DELETE operation handling
  • Added stub calendar service for testing environments

​
Feb 14, 2026

​
E2E testing & org provider improvements

  • Added stale org self-healing coverage to OrgProvider
  • Guard org refresh with useRef to prevent redundant calls
  • Migrated web quality checks to tsgo and oxc tooling

​
Feb 11, 2026

​
OpenAPI Spec & Error Standardization

  • Added OpenAPI 3.1 spec auto-generated from handler annotations via swaggo
  • Added CI step to generate and publish OpenAPI spec artifact
  • Sentry log handler now respects configured minimum log level

​
Jan 26, 2026

​
Finance Module

  • New proto: finance/v1/finance.proto

​
Key Vault Migration

  • Migrated sensitive env vars to Azure Key Vault
  • Added private endpoint access
  • Improved secret rotation capabilities

​
Nov 30, 2025

​
Initial Release

  • Go API backend
  • Azure infrastructure deployment