Story-779 Lane: admin Walkthrough Doctrine

Admin walkthroughs publish themselves after merge

This story gives pramaan-admin the same low-friction publishing path already proven in pramaan-functions: merge a walkthrough HTML file, let GitHub Actions upload it, and make the public URL live without a human S3 step.

The product shape

PRAMAAN staff use admin as an internal control room. When a change is operationally meaningful, the walkthrough is the durable teaching artifact: what changed, why it matters, and how future engineers should reason about the implementation.

The old failure mode was not conceptual. People could write good walkthroughs. The gap was mechanical: publishing depended on remembering a separate upload path. Story-779 removes that memory tax from pramaan-admin.

Before HTML could land in the repo but remain invisible unless someone manually published it.
After Merging docs/walkthroughs/story-779-walkthrough.html to main publishes 779.html.
Invariant The public namespace stays flat: https://walkthroughs.pramaan.io/779.html.

The engineering path

The workflow is intentionally boring. It watches walkthrough HTML files, infers the story number from the filename, uploads to the shared S3 bucket, rebuilds the index, and invalidates CloudFront.

1. Detect
On pushes to main, the workflow reads changed files under docs/walkthroughs/*.html. On manual dispatch, it scans all walkthroughs.
2. Publish
The workflow maps story-779-walkthrough.html to the flat S3 key 779.html, then uploads with a short browser cache window.
3. Refresh
It rebuilds index.html from bucket contents and invalidates both the story URL and index paths through CloudFront.

The trust boundary

The local workflow file is only half the rollout. GitHub Actions must be allowed to assume the shared AWS role from pramaan-admin/main. That trust policy is the real permission gate.

"token.actions.githubusercontent.com:sub": [
  "repo:pramaan-io/pramaan-functions:ref:refs/heads/main",
  "repo:pramaan-io/pramaan-app:ref:refs/heads/main",
  "repo:pramaan-io/pramaan-admin:ref:refs/heads/main"
]

The mental model is simple: the workflow describes the action, repository secrets point to shared infrastructure, and the IAM role decides whether this repository is allowed to act.

What future stories inherit

Future admin walkthroughs only need a correctly named HTML file in docs/walkthroughs/. The workflow turns that into a public artifact and keeps the index current.

That makes walkthrough publishing part of the normal PR lifecycle instead of a separate release ritual. For an internal operations product, that matters: the explanations stay attached to the exact changes that created them.