Story-780 docs lane walkthrough publishing

pramaan-docs can publish walkthroughs automatically

The docs repo now uses the same flat-key publishing path as the production reference workflow.

Issuepramaan-spec#780
Target repopramaan-docs
Public artifact780.html

TL;DR

Story-780 copied the proven walkthrough publisher from pramaan-functions, changed its repo identity to pramaan-docs, and added this walkthrough so the first docs-repo run has a concrete HTML artifact to upload.

1 Why this exists

Walkthroughs are now part of PRAMAAN's engineering memory. They explain not only what changed, but how a future engineer should reason about the work. That only works if the artifacts are easy to find after merge.

Before this Story, pramaan-docs already held walkthrough HTML under docs/walkthroughs/, but it did not have the GitHub Actions pipeline that publishes those files to the shared public walkthrough domain. The product problem was not authoring; it was distribution.

Mental model

The repo is the source of truth, S3 is the shelf, and CloudFront is the reading room. A merge to main should move the new walkthrough from the source shelf to the public room without a human carrying it by hand.

2 How the pipeline works

The workflow watches for changed HTML files in docs/walkthroughs/. For each matching file, it extracts the Story number from the filename, uploads the file as a flat S3 key such as 780.html, rebuilds the public index, and invalidates CloudFront.

Walkthrough publish flow A merged walkthrough file moves through GitHub Actions, OIDC, S3, index rebuild, and CloudFront invalidation to the public URL. Merge to main docs/walkthroughs GitHub Action detect + upload S3 flat key 780.html Index rebuild numeric files only CDN live OIDC trust repo must be allowed

3 What changed

.github/workflows/publish-walkthroughs.yml

Copied from the production reference workflow in pramaan-functions. The important repo-local change is REPO_NAME: pramaan-docs; the flat S3 key logic stays the same.

docs/walkthroughs/story-780-walkthrough.html

This file is the Story-owned teaching artifact and the smoke-test payload. After merge, the workflow should publish it as https://walkthroughs.pramaan.io/780.html.

The external setup is part of the Story too: the shared publisher role must trust pramaan-docs, and the docs repo must have the three publishing secrets. Those values live in GitHub/AWS configuration, not in this public file.

4 Decisions preserved

The critical architectural choice is the flat namespace. Public URLs are keyed by Story number, not by repo path. That means story-780-walkthrough.html becomes 780.html, and the index only lists numeric HTML keys.

Gotcha

The workflow can be syntactically valid and still fail at runtime if IAM trust is missing. OIDC trust is the bridge between GitHub Actions and AWS; without it, the action cannot assume the publisher role.

5 Reading order

  1. Start with .github/workflows/publish-walkthroughs.yml and follow the job from change detection to CloudFront invalidation.
  2. Read the Upload walkthrough HTML step carefully; it is where filenames become flat public keys.
  3. Read the Rebuild index step; it explains why only numeric HTML keys appear on the public index.
  4. Then read this walkthrough as the first docs-repo payload for the pipeline.

6 Check yourself

  1. If a file is named story-780-walkthrough.html, what S3 key should the workflow write?
  2. Why does adding the workflow file alone not prove the rollout works?
  3. Why should the workflow preserve existing trusted repos when updating IAM trust?

Answers: 780.html; because OIDC trust, secrets, and a real workflow run are required; because the publisher role is shared and replacing the trust list would break already-active repos.