[grabngostuff]

debugging-workflows had no answer for three things that cost time on live apps. When a released UI fix doesn't show, it now says to grep the built src/dist and rebuild if the change is missing, since deploy ships dist/ as is. When releases stay "In progress", it says to stop retrying, open a support ticket, and, to keep shipping, deploy as a new app under a new name, with the cost of that spelled out. It also lists the deserializeSitemap and uilogging 400 console errors as Falcon console noise, not app errors.

To stay within the SKILL.md size budget, the function runtime table, the install-failure steps, and the screenshot guidance move into two new reference files, with pointers left in SKILL.md.

[mraible]

Thanks Dan. The console-shell noise row will save people a lot of time chasing errors that aren't theirs.

CI: the validate job fails because SKILL.md is over the 5,500-token size budget (CI estimates tokens as characters / 4). That budget follows the Agent Skills spec, which recommends keeping the SKILL.md body under 5,000 tokens and 500 lines, since the whole file loads every time the skill triggers. Most skills are already at 96-99% on main, so the fix is to move the long walkthroughs into the skill's references/ folder and leave a one- or two-line pointer in SKILL.md. Common Pitfalls rows can stay short, with the detail in the reference file.

Content:

• Jammed release escape. "Strip the provisioned IDs and deploy as a new app" also needs a new name. The Manifest Issues section in this file says that dropping the IDs while keeping the name fails with an app with the provided name already exists, and the stuck app still exists here. Please add the rename.
• "On some apps the in-console preview is effectively broken." Do you know what makes preview break, such as particular sockets, extensions vs. pages, or a CSP setting? Without that, readers may decide preview never works and skip foundry ui run entirely. If the cause isn't known yet, I'd keep only the dist-grep tip.
• The new tree entry repeats the new section instead of pointing to it the way other leaves do ("see Preview Is Unreliable"), and it's filed under foundry ui run fails even though the symptom is a released change that doesn't show up. Please also line its arrow up with the others in the tree.
• #144 adds the same dist-grep advice to development-workflow. One home for it, linked from the other, would be best.

[grabngostuff]

Thanks @mraible — size-budget failure fixed. Moved the Function Runtime Debugging loop, App Install Failures, and Visual Debugging walkthroughs into references/ with short pointers; kept the Common Issue Patterns table inline; CHANGELOG trimmed. SKILL.md is now ~19,992 chars (~4,998 tokens), under the 5,500 budget. Relocated, not removed. Ready for re-review.

[mraible]

Thanks Dan, the size budget is fixed. The content points from the last review are still open, and there's one new CI problem:

• markdownlint will fail. references/install-and-visual-debugging.md now has two top-level headings (# Debugging App Install Failures and # Visual Debugging with Screenshots), which trips MD025. Making the second one ## fixes it.
• Jammed-release escape. "Strip the provisioned IDs and deploy as a new app" still needs a new name too. The stuck app still exists, so keeping the name fails with an app with the provided name already exists.
• "On some apps the in-console preview is effectively broken." If you know what triggers it, please say so. If not, I'd keep just the dist-grep tip so readers don't stop using foundry ui run altogether.
• The tree entry still repeats the section instead of pointing to it ("see Preview Is Unreliable"), still sits under foundry ui run fails though the symptom is a released change that doesn't show, and its arrow still doesn't line up with the others.
• The dist-grep tip is also in #144. One home, linked from the other.

CI on your latest push is waiting for maintainer approval, so I ran the checks locally: size budget and tests pass, and markdownlint fails as above.

[mraible]

Confirmed the MD025 fix: with the second heading changed to ## Visual Debugging with Screenshots, markdownlint passes with the repo config.

[grabngostuff]

Pushed a fix for the failing markdownlint (MD025): the new references/install-and-visual-debugging.md had a second top-level H1 — demoted it to H2. Verified locally green — markdownlint 0 errors across the repo glob, content tests 67/67, size validate pass. Ready for a CI re-run + re-review.

[mraible]

Thanks Dan, the size budget and the MD025 fix both look good. The content points from the last review are still open:

• Jammed releases. The escape still says to cold-deploy a fresh app_id without mentioning the app's name. Reusing the name fails (see the Manifest Issues section), so please add that the new app needs a new name.
• "On some apps the in-console preview is effectively broken." Please either name the cause, or cut this down to the dist-grep tip, which is the useful part.
• The decision-tree entry. It still repeats the full sentence instead of pointing to the section ("see Preview Is Unreliable"), it sits under foundry ui run fails, which isn't the symptom, and its → doesn't line up with the rows around it.
• The dist-grep tip is also in development-workflow: operate-an-existing-app lifecycle gotchas #144. Please keep it in one place and link to it from the other.
• Minor: "open the workflow in Fusion SOAR" in the install-failures pointer needs the Falcon prefix ("Falcon Fusion SOAR").

CI passes on your latest push, so these content points are all that's left.

[mraible]

Thanks Dan, this is ready to merge.