Last updated 2026-05-07

Generating Feature Documentation

Each feature in stax can ship with structured documentation: a written description, a Playwright-recorded walkthrough video, annotated screenshots, and a cross-link to the relevant diffs. The pieces live next to each other under .stax/features/<slug>/ and are aggregated by the dashboard.

Anatomy of a feature folder

.stax/features/<slug>/
├── feature.md                 # narrative description (commit-tracked or local)
├── video-capture/
│   ├── demo.mp4               # primary walkthrough
│   ├── thumbnail.png          # auto-generated still
│   └── screenshots/
│       ├── launch-screen.png
│       ├── form.png
│       └── ...
└── diffs.json                 # produced by the CLI

1. Start with a feature

stax feature "onboarding redesign"
# ... ship a couple of diffs ...
stax diff "Add new welcome screen"
stax diff "Wire up form validation"

2. Write the narrative

Drop a feature.md in .stax/features/onboarding-redesign/. The dashboard renders it on the feature page.

# Onboarding redesign

## What changed
A new two-step welcome screen replaces the previous full-form sign-up.
Fields are validated inline and the submit button is enabled only when
the form is valid.

## Why
Conversion through the previous form was 38%. The hypothesis is that
breaking the form into two screens reduces cognitive load.

## How to verify
Open /signup and walk through both screens. Try invalid emails to see
inline validation. The Playwright video below captures the canonical
flow.

3. Record a walkthrough

Run the video-capture workflow against the feature slug (see the video demo recipe):

stax run feature-video -i feature=onboarding-redesign

The artifacts land in .stax/features/onboarding-redesign/video-capture/.

4. View it

stax dashboard

The page renders the description, video, screenshot strip, and a list of linked diffs in stack order. Reviewers click into individual diffs (powered by the Monaco-backed viewer) for the actual code review.

5. Ship the docs alongside the code

The feature.md typically lives in .stax/features/... which is excluded from git via .git/info/exclude. If you want the docs to ship with the repo (recommended for marketing-grade walkthroughs), move them under docs/features/<slug>/ and commit them — the dashboard auto-discovers either location.

6. Automate it

Wire the video capture into your release pipeline. When a PR lands on main, generate the demo video and upload it as a release artifact:

name: Release docs
on:
  push:
    branches: [main]
    paths: ['.stax/features/**']

jobs:
  capture:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - id: changed
        run: |
          slug=$(git diff --name-only HEAD~1 HEAD \
            | grep '.stax/features/' \
            | head -1 \
            | awk -F/ '{print $3}')
          echo "slug=$slug" >> $GITHUB_OUTPUT
      - uses: ./platform/actions/video-capture
        with:
          platform: web
          app-url:  http://localhost:3000
          scenario: ./scenarios/${{ steps.changed.outputs.slug }}.yml
          output-dir: ./.stax/features/${{ steps.changed.outputs.slug }}/video-capture