Story-778 app lane Size M Walkthrough

Walkthrough auto-publishing for pramaan-app

The app repo now publishes merged walkthrough HTML to the shared public walkthrough site.

Issue pramaan-spec#778
Parent Walkthrough Doctrine
Built by Conductor agent on 2026-05-21

The 30-second version

Story-778 gives pramaan-app the same publishing path already used by pramaan-functions: when a walkthrough file like docs/walkthroughs/story-778-walkthrough.html lands on main, GitHub Actions assumes the shared AWS publisher role, uploads it as 778.html, rebuilds the index, and invalidates CloudFront.

Why this matters

A walkthrough is only useful if people can read it without spelunking through a repository. The engineering habit we want is simple: ship the code, ship the explanation, and make the explanation public from the same merge.

The mental model is a release note with a real publishing pipeline behind it. The HTML file is the source. The merged PR is the trigger. S3 and CloudFront are the shelf where everyone can find the result.

The pipeline shape

Merge to main
walkthrough HTML changes
->
GitHub Actions
OIDC into AWS role
->
Public URL
walkthroughs.pramaan.io/778.html

The important implementation detail is the flat S3 key: story-778-walkthrough.html becomes 778.html. That keeps the public URL stable and short, while the repo-local filename keeps enough context for humans.

What changed in pramaan-app

  • Added .github/workflows/publish-walkthroughs.yml, copied from the production-fixed pramaan-functions workflow.
  • Set REPO_NAME to pramaan-app so index and notification metadata name the right source repo.
  • Added this Story-778 HTML walkthrough so the first app-lane publish has a concrete artifact to upload.
  • Configured the shared AWS trust policy and app repo secrets outside the public repository files.

What to verify after merge

After the PR lands on main, run the workflow manually once from GitHub Actions or with gh workflow run publish-walkthroughs.yml --repo pramaan-io/pramaan-app. A green run proves the OIDC role, secrets, S3 upload, index rebuild, and CloudFront invalidation all agree.

The final product check is concrete: https://walkthroughs.pramaan.io/778.html should load this page.