Technical reference. For task-based help, see the corresponding user guide.

Documentation status: complete for the current implementation

Reviewed: 2026-07-21

Primary users: subscribed coaches

Surfaces: coach admin portal, platform API and protected file storage

Sleep-plan authoring gives an assigned coach one working plan for a family and a durable, read-only history of plans the coach deliberately archives. The working plan can combine structured paragraphs, bullet points, images and an optional PDF. A coach may keep it private as a draft or publish it into the family's mobile sleep-plan library.

The lifecycle distinguishes local edits, a durable draft, a family-visible publication and archived history. Those states matter: publishing is the only action that makes current content visible to the family, while archiving removes the current publication and starts a clean next version.

Opening Session Prep calls the singular coach read. If no current plan exists, that read creates version 1 as a draft titled Sleep plan with starter sections for Goals, Bedtime routine, Night wakes and Naps.

Each plan record is scoped to organization, coach and family, and contains:

1. a stable record ID and positive version number;
2. a title;
3. 1–30 ordered sections;
4. up to 80 blocks in each section;
5. optional PDF asset metadata;
6. draft, published or archived status; and
7. creation, update, publication and archive timestamps as applicable.

Section titles and the plan title are limited to 180 characters. Paragraph and bullet text is limited to 4,000 characters per block. Image block identifiers are limited to 80 characters; filename, content type and asset path are validated, while alt text and caption are each limited to 500 characters.

1. Add section appends a starter section with one paragraph.
2. A section title is required by the server.
3. The final remaining section cannot be removed.
4. Sections can be reordered by dragging the handle.
5. With the handle focused, Arrow Up and Arrow Down provide a keyboard reorder path.
6. The saved section array is the authoritative display order in family and archived views.

Each section has a plain-text area that maps non-empty lines to blocks:

1. a line beginning exactly with ''- '' becomes a bullet block;
2. every other non-empty line becomes a paragraph block; and
3. blank lines are omitted.

Editing that text area rebuilds the section's text blocks, then retains its existing image blocks after them. The current editor therefore does not interleave images between individual paragraphs or expose block-by-block reordering inside a section. The 80-block server limit counts paragraphs, bullets and images together.

Add image accepts JPEG, PNG, WebP or GIF files no larger than 10 MB before client-side compression.

1. JPEG, PNG and WebP are resized to at most 2,000 pixels on their longest side and encoded at quality 0.82 only when the result is smaller than the original.
2. The browser prefers WebP when supported, then falls back to the original compatible format.
3. GIF files are uploaded unchanged so animation is not flattened.
4. A successful upload creates an image block with asset path, original display filename, content type and upload time.
5. The coach can edit a caption and accessibility alt text, preview the image or remove its reference from the draft.

Images use the sleep-plan-images bucket. Preview/download requests use short-lived signed URLs with a requested lifetime of 900 seconds; storage is not public.

The editor accepts application/pdf or a .pdf filename up to 20 MB and uploads it to sleep-plan-pdfs. Once attached, the coach can download it through a fresh 900-second signed URL or remove its metadata from the plan draft.

The structured plan and PDF are complementary. A plan can have either or both; publishing does not require a PDF.

File upload is a two-stage process:

1. the portal asks the platform for a signed upload URL scoped to the assigned family and permitted bucket/path;
2. the browser uploads directly to protected storage; then
3. the new asset metadata is placed only in the local plan draft.

After a successful upload, the portal explicitly says to Save draft or Publish to keep the attachment. If signing or upload fails, the plan is not given a durable asset reference and the coach can retry. If the upload succeeds but the coach abandons or removes the unsaved edit, the current UI does not issue a storage-object deletion; the uploaded object may remain unattached until storage lifecycle/cleanup handles it.

Signed URLs can expire while a screen is open. Reloading the preview or asking to download again obtains a new URL; applications must never persist a signed URL as plan content.

Changing text, order, files or image metadata marks the plan dirty only in the current browser. If the durable record is already published, the family continues to see the last published server version until the coach saves or publishes.

There is no plan revision token or expectedUpdatedAt in the write contract. Concurrent coaches/tabs therefore use last-write-wins behavior, and a stale tab can replace newer content.

Save draft writes the complete current plan with status draft.

1. A new or existing draft remains hidden from family endpoints.
2. Saving a previously published plan as draft withdraws it from the family's list and clears publishedAt.
3. The same current record and version number are retained.
4. A successful response replaces local state and clears the dirty marker.

Publish writes the complete plan with status published.

1. The family can see the durable result only after this request succeeds.
2. The first publication timestamp is retained across subsequent writes that keep the plan published.
3. If the plan was saved back to draft, publishedAt was cleared and the next publication establishes a new publication timestamp.
4. A published plan with local dirty edits is labelled Published with unsaved edits; Publish changes replaces the family-visible version.
5. When no edits are pending, the published action is disabled and labelled Published.

The platform is designed to retain exactly one non-archived working record for the coach-family relationship. History contains records whose status is archived, sorted newest archive first and then by version.

Versions identify records, not every save. Saving draft or publishing edits keeps the current version. Archiving creates the next record/version.

Archive current is disabled while local edits are dirty; the coach must save or publish first. The platform then performs one transaction:

1. changes the current record to archived and records archivedAt;
2. immediately removes it from family-visible published results; and
3. creates a clean draft from the standard starter content using one more than the highest existing version.

The newly created draft becomes the editor's current plan. The archived record, including its status at the moment of archiving, structured content and asset metadata, remains in Plan history.

Each history row shows version, title, archive date and section count. View opens a read-only rendering of its paragraphs, bullets, images and PDF filename. Archived image previews still require authorized signed-download requests.

Restore is deliberately a copy operation:

1. the selected archived record remains unchanged in history;
2. its title, sections, image metadata and PDF metadata replace the current working record;
3. the current record becomes draft, with no publication timestamp; and
4. family visibility is not restored until the coach explicitly publishes.

If a current record already exists, its identity and version stay the same. If none exists, the server creates a new next version. The portal asks before replacing unsaved local edits.

Remove asks for confirmation and deletes only the selected archived database record. It does not alter the current plan. If an inconsistent state has no current record, the service repairs the invariant by creating a new draft. The operation cannot be undone from the UI; removal of the database record does not itself constitute a storage-bucket purge of referenced files.

Family-facing GET /families/me/sleep-plans returns only published records for the signed-in family's current assignment and is documented in Feature 13.

1. Every authoring/history route resolves the requested family through a matching active coach assignment rather than accepting arbitrary client scope.
2. Access also requires active organization membership, an active/trialing organization, qualifying coach subscription and a support entitlement that permits record access.
3. Paused support still permits record access; expired, revoked, canceled or inactive-billing access does not.
4. Plan IDs and file paths are rechecked against coach, organization and family scope on every request.
5. Family routes filter to published and cannot ask for an archived ID or obtain a draft signed URL.
6. Storage buckets remain private; durable plan records contain asset paths, never permanent public URLs.

1. A family relationship has one current plan and may have multiple archived records.
2. The editor round-trips ordered sections, paragraph/bullet/image blocks and optional PDF metadata within contract limits.
3. Image/PDF type and size validation occurs before upload, and successful uploads still require a plan save.
4. Draft records are absent from family responses; only a successful publish makes content visible.
5. Saving a published plan as draft withdraws it and clears publication time.
6. Archive is atomic and starts the next clean version without losing the archived source.
7. Restore copies to a draft, preserves history and never republishes automatically.
8. Permanent removal targets only an archived record in the authorized assignment.
9. Stale-tab last-write-wins behavior and possible unattached uploads are treated as current operational caveats.

• admin-web/src/routes/SessionPrepArtifactsPanel.tsx
• admin-web/src/routes/SessionPrepPanel.tsx
• admin-web/src/api/client.ts

• platform/apps/api/src/routes/coach-routes.ts
• platform/apps/api/src/routes/family-routes.ts
• platform/apps/api/src/routes/file-routes.ts
• platform/apps/api/src/services/family-profile-artifact-service.ts
• platform/packages/shared/src/family-profile-artifacts.ts
• platform/packages/shared/src/files.ts

• 13 — Published sleep plans
• 18 — Session prep and coach report
• 20 — Questionnaire template management