Skip to content

Naluma App Content — production & authoring handbook

This is the documentation for naluma-app-content: the source of truth for the Naluma mobile app's content — guided sessions (incl. insight), ambient sounds, and coach conversations — plus the production pipeline that renders, validates, and publishes them.

Scope — what this site is, and isn't

This is the production & authoring handbook (code-adjacent + authoring reference). It is not product strategy or cross-cutting decisions — those live in the naluma-root knowledge base. One home per fact: link across the boundary, never copy.

Where to start

  • Authoring — editorial voice, AI-writing patterns, and the per-type authoring standards (audioGuided, breathing, insight, the interactive types, sounds, coach conversations).
  • Protocols — the clinical grounding (ACT / CBT / TRT for tinnitus) the content draws on.
  • Research — the evidence base and positioning behind the content.
  • Architecture — design specs for the production system (audio pipeline, seeder, localization, publishing rails).
  • Reference (generated) — the content catalog + status/coverage, CLI reference, schema contracts, Python API, and the coach schedule. Regenerated on every deploy from the source files — never hand-edited.

How this site stays current

Two kinds of pages, two disciplines:

  1. Generated reference is never hand-edited — it's derived from frontmatter, argparse parsers, JSON schemas, docstrings, and CSV, and rebuilt on every deploy. If a reference page is wrong, fix the source artifact, not the page.
  2. Handwritten docs are edited in docs/ via pull request, like code; merging to main republishes the site automatically.

When a change alters something the docs describe, update the doc in the same PR. Durable gotchas/conventions live in the repo's CLAUDE.md (the agent-facing source of truth); this site mirrors them for humans. Full rules: see the docs-site design spec under Architecture.

Access

The whole site is behind Cloudflare Access (Naluma team only). Everything here — including research and IP/licensing notes — is internal. Never put secrets (tokens, keys) in docs; those are governed by the secrets inventory.