docs(web): reframe the site around the staged loop, not attach-first#417
Merged
Conversation
Staging has no time-based cleanup — promotion is copy-and-keep, so an already-embedded URL keeps serving. The only real time bound is promotion's 30-day freshness window (files staged past that are skipped, not deleted). Fix the false "~7/~30 day cleanup" claim in github-app.astro and the CLI README, and update the put example to show the branch-staged default (issue #403) instead of the classic dated layout.
0.24.0 inverted the story: a bare `put` on a branch stages automatically (#403), so agents can capture at every visual milestone while they work and the PR opens already furnished — no upload command needed at PR time. `uploads staged` (#405) shows what's queued and whether it'll auto-attach. - Homepage hero terminal walks the new loop (put while working → gh pr create → already furnished); lede, meta descriptions, and the features grid follow; agentPrompt teaches the staged loop end to end. - Docs hub gets a "start before the PR exists" beat. - Attach & share promotes staging from an aside to a first-class section with its own TOC entry, covering `uploads staged` and binding states. - Agents guide's stage-as-you-go section drops the `--branch` flag from its recipes and swaps the `find gh.branch=` shell backstop for `uploads staged --format json`. - Reference lists `uploads staged`. - llms.txt's attach & share blurb mentions staging.
Deploying with
|
| Status | Name | Latest Commit | Preview URL | Updated (UTC) |
|---|---|---|---|---|
| ✅ Deployment successful! View logs |
uploads-web | 470133c | Commit Preview URL Branch Preview URL |
Jul 22 2026, 07:55 PM |
|
Important Review skippedAuto reviews are limited based on label configuration. 🏷️ Required labels (at least one) (2)
🚫 Excluded labels (none allowed) (1)
Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
📎 Attachments
Maintained by uploads.sh — re-uploading a file with the same name updates it everywhere it is embedded. |
The example invented a "(staged for branch X)" suffix on put's uploading line — that shape is only ever printed by attach --branch (runAttachBranch). Bare put's uploading line has no such suffix; the staging signal is the trailing note line and the branch-keyed URL. Also dropped the content-hash suffix from the staged key — staged keys are stable per filename (ghBranchAttachmentKey, no hash), unlike the dated layout's hashed keys. Added a sentence calling out that difference since it's otherwise easy to miss between the two examples.
…amples Same class of bug as the docs/staging-correctness fix, now merged forward: several examples invented a "(staged for branch X)" suffix on put's uploading line (only attach --branch prints that), and one example left an unsanitized "/" in a branch-staged key (ghBranchAttachmentKey sanitizes the branch to one segment, feat/nav -> feat-nav). Fixed in the homepage hero terminal, the docs hub's "start before the PR exists" example, and the staging section's `uploads staged` example output. The hero's note line now truncates the real note text with a real ellipsis instead of paraphrasing it.
Put the plain-sentence version of staging up front and move the opt-out flag list / no-hash detail to a Details note at the bottom of the section, after both examples. Compress the promotion-retention paragraph on the GitHub App page to the one-sentence contract first, then the freshness caveat last and brief.
Homepage lede drops all code spans and the trailing "point uploads attach" detail sentence — the terminal right below already shows the real commands. Meta/og/twitter descriptions follow the same plain- language rule. The "stage as you go" and "device frames" feature cards trim to at most one code literal each, phrasing the rest plainly. The docs hub's "start before the PR exists" beat trims to one lead-in sentence, the example, and one payoff sentence. One light-touch fix on the attach & share page where a code span was pure restatement.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Stacked on #416 (
docs/staging-correctness) — merge that one first. Thisbranch is based on it, so the diff here is scoped to the story reframe.
Summary
The site told an attach-first story ("have a PR, run attach"). Since 0.24.0
(#403 bare
putstages by default on a branch; #405uploads staged), theactual differentiator is the inverted loop: upload while you work → it's
already staged for the branch → the PR opens already furnished, with zero
upload commands at PR time. This reframes the site around that loop, matching
the story already told in
docs/deletion.md,skills/github-screenshots/SKILL.md, andskills/uploads-cli/SKILL.md.index.astro): hero terminal now walksuploads put(staged,no PR yet) →
gh pr create→ "your PR opens already furnished" → the samewireframe comment. Lede,
<meta>description, og/twitter descriptionsupdated to lead with the loop while still naming
uploads attachas theexplicit form. The features grid swaps "update-in-place comments" for a
"stage as you go" card (
uploads staged, binding, copy-and-keep); theupdate-in-place fact moved into the lede.
agentPrompt(the copyable agentsetup prompt) now teaches the staged loop end to end.
docs.astro): new "Start before the PR exists" beat rightafter the two-command overview.
attach-pull-request-images.astro): staging promotedfrom a "No PR yet?" aside to a first-class section (own TOC entry) —
attach --branchas the explicit multi-file form,uploads staged(
--branch,--format json), the binding states (self/none/other/unknown,linked to the GitHub App page), and the durability sentence (copy-and-keep).
agents.astro): stage-as-you-go section and theAGENTS.md snippet drop the now-unnecessary
--branchflag from a bareput; thefind gh.branch=…shell backstop is replaced withuploads staged --format json(always a valid document, even at zerofiles).
reference.astro): addeduploads stagedto the commandlist.
llms.txt's "Docs: attach & share" line now mentions staging.No new solid CTAs; existing width tokens and
 whitespace pattern keptas-is.
Screenshots
Homepage hero, before vs. after, attached below via
uploads attach(see themanaged 📎 Attachments comment). Captured locally: a static server over the
built
dist/clientfor "after", the shared dev server (still onmain'scopy at the time) for "before", both via
uploads screenshot --no-upload --out+uploads attach. This environment'sshared preview infrastructure serves from the main checkout rather than this
worktree, so the dev-server route to the "after" state wasn't usable — the
static-server workaround above stood in for it.
Test plan
pnpm --filter @uploads/web build— succeeds, verified rendered outputin
dist/client/index.htmlfor the new copypnpm test— 204 files / 2568 tests passpnpm typecheck— 0 errorspnpm run format:check— clean