docs: fix SDK version staleness, document the SDK-bump failure mode - #20
Merged
Merged
Conversation
The deploy page claimed a specific required aomi-sdk version in prose. That number moved twice in a week (3.0.1 -> 3.0.2 -> 3.0.3), so the claim was already wrong and the sample output had drifted internally inconsistent. - Removes the hardcoded 'the required version is X' claim; sample output is now internally consistent and labelled as an example, with a warning never to copy a version number out of the page. - Adds 'When the platform bumps the SDK': an SDK bump silently stops every release built against the old pin from loading. The App vanishes from the picker with active=true but artifact_ready=false. Documents the tell, the confirmation, and the redeploy fix. - Adds troubleshooting rows for that failure mode and for the deploy 502 (fixed by running source sync first). - Adds 'Verified <date>' stamps to both pages so staleness is visible. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
This PR updates the Build docs to prevent aomi-sdk version guidance from going stale and to document the common “platform bumped required SDK” failure mode so builders can diagnose and recover when a previously-working deployed App stops loading.
Changes:
- Adds “Verified YYYY-MM-DD” stamps to Build pages to make staleness visible.
- Updates SDK check/fix example output to be internally consistent and adds a warning not to copy version numbers from docs.
- Documents the “platform bumps the SDK” scenario (symptoms, confirmation, and redeploy fix) and adds related troubleshooting rows.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| build/frontend-vercel.mdx | Adds a verification stamp and guidance to trust the package registry/install over doc-stated versions. |
| build/deploy-cli.mdx | Refreshes SDK check/fix examples, adds an explicit warning about version staleness, documents the SDK-bump failure mode, and expands troubleshooting. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| This guide takes an App from your own GitHub repo to live on Aomi, using the `aomi-build` CLI. You work in your own repo the whole time. You never open a PR against `aomi-labs/community-apps`, and you never need write access to it. The backend does that part for you through the Aomi GitHub App. | ||
|
|
||
| <Info> | ||
| **Verified 2026-07-14** against a live community deploy on `https://api.aomi.dev`. Command output on this page is real, not illustrative. Version numbers move: always trust `aomi-build sdk check` over any number written here. |
| aomi-build deploy --platform community --repo you/my-app --target-tag prod | ||
| ``` | ||
|
|
||
| Your App is back once you see `active=true artifact_ready=true loaded=true`. |
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
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.
Why
Two problems found while grading the deploy docs against live state.
1. A stale fact was live.
build/deploy-clistated "As of July 2026 the required version is3.0.1". The real requirement is now 3.0.3 — it moved twice in one week (3.0.1 → 3.0.2 → 3.0.3). The sample output had also drifted internally inconsistent (one block showedRequired: 3.0.3alongsideDependency: exact 3.0.1).2. The most likely real-world failure wasn't documented. When the platform bumps the required SDK, every release built against the old pin silently stops loading. The App disappears from the chat picker with no warning — and
active=truestill reads as healthy, so it's easy to misdiagnose. Hit live on bothgoal-digger-liveandmonad-oneshotthis week.What changed
<Warning>never to copy a version number out of the page — runaomi-build sdk checkinstead. This is the durable fix; updating the number to 3.0.3 would just go stale again.artifact_ready=false+not loadedwhileactive=true), how to confirm it, and the redeploy fix, with a note that it applies to every deployed App.502(fixed by runningsource syncfirst).Verified <date>stamps on both Build pages so staleness is visible rather than invisible.Verified
mint broken-linkspasses;docs.jsonvalid.🤖 Generated with Claude Code