A small workflow fix that puts published walkthroughs where doctrine says readers will find them.
The publish workflow used a repo-shaped S3 key, pramaan-functions/story-774.html. The walkthrough doctrine and existing objects use a flat public key, 774.html. This fix makes upload, index rebuild, tests, and docs agree on the flat shape.
The original workflow copied the local file naming convention into the public URL. Local files are intentionally descriptive, like docs/walkthroughs/story-774-walkthrough.html, because engineers browse them in a repo. Published URLs serve a different job: they are permanent reader-facing addresses.
The workflow crossed those two ideas and uploaded to <repo>/story-<N>.html. That looked tidy from a repository perspective, but it contradicted the locked walkthrough doctrine and the nine objects that were already published flat.
Mental model: local filenames are labels on working documents. S3 keys are public shelf addresses. A good shelf address should match the catalog readers were promised.
Epic-762 locked the public URL pattern as walkthroughs.pramaan.io/<N>.html. That means Story 722 lives at 722.html, not pramaan-functions/story-722.html.
The flat pattern also matches the product use case. Walkthroughs are consumed as a cross-repo learning archive. Readers care about the issue number first; the repo is context inside the document, not a folder they should need in the URL.
The upload change is deliberately tiny. The workflow still extracts the number from story-<N>-walkthrough.html, but it now uses that number directly as the object key.
Before: key="$REPO_NAME/story-$story.html"
After: key="$story.html"
The index rebuild needed the matching conceptual change. It no longer splits keys into repo and filename. It accepts only flat numeric HTML keys like 774.html, reads the title from the page's first <h1>, and sorts rows by issue number descending.
Nested keys would make sense if each repo owned a separate walkthrough archive. PRAMAAN does not. The distribution is one public archive backed by one bucket and one index.
Flat keys make the contract easy to test and easy to explain: issue number in, same issue number out. They also avoid future repo-name churn in public links. If a walkthrough moves between repos or teaches a cross-cutting concept, the public URL does not need to care.
This change does not rename local files. The publisher still expects story-<N> in the local filename so it can infer the issue number. Only the S3 key and public URL become flat.
The focused unit test reads the workflow and publishing doc as contracts. It now asserts the flat upload key, flat index parsing, story-number sorting, and absence of repo grouping.
The docs smoke test now checks s3://pramaan-walkthroughs/722.html and opens $WALKTHROUGH_BASE_URL/722.html. No IAM role, secret, CloudFront, or Slack notification shape changed in this bug.
story-<N>?