ForgeBoard Operations Plan

Health Oddities Cleanup Plan

Working plan for clearing up inconsistent, goofy, or hard-to-trust health-board behavior while preserving the rule that ForgeBoard tells the truth first.

Source: /Users/adamo/forgeapps/apps/forgeboard/plans/health-oddities-cleanup-plan.md Rendered: 2026-07-02 13:21:42 UTC

ForgeBoard Health Oddities Cleanup Plan

Purpose

Track odd or inconsistent health-board behavior discovered while pursuing the 100% of Apps 100% Green goal. These are not excuses to weaken checks. They are cleanup targets so ForgeBoard can tell the truth in a simpler, more cookie-cutter way locally and in production.

Current Truth

Current Sentry Blocker Breakdown

Source: live ForgeBoard UI, live ForgeBoard org proxy https://board.forgefx.dev/api/sentry-org-issues?org=kane-research, and direct Sentry project issue queries on 2026-07-02.

Production Probe Notes

Source: in-app browser production visits on 2026-07-02.

Stale Sentry Issues Resolved After Reproduction

Source: direct production-page browser probes followed by Sentry issue API updates on 2026-07-02.

Verified Remediation

Source: local ForgeBoard code changes on 2026-07-02.

Oddities

1. ForgeBoard Sentry Project Was Still Named dashboard

Evidence: SENTRY_PROJECT_MAP.forgeboard pointed to the dashboard Sentry project while the app, docs, route, and live domain were already ForgeBoard.

Why it is goofy: ForgeBoard no longer lives at apps/dashboard, and a lingering dashboard Sentry slug makes the app registry less cookie-cutter than the rest of the fleet.

Cleanup status: fixed on 2026-07-02. The Sentry project slug and display name are now forgeboard, and ForgeBoard's project map points at the forgeboard slug while keeping the same numeric project id.

2. Sentry Environment Defaults Are Mixed

Evidence: SENTRY_ENVIRONMENT_MAP overrides only a few apps, with ForgeBoard mapped to development while its live domain is production. Most apps fall back to development.

Why it is goofy: The app-card lights are checking production readiness, but the Sentry environment labels can read as development. That makes failures harder to reason about and can hide whether production users are actually generating session proof.

Cleanup target: make Sentry environment naming consistent across apps. Prefer production bundles reporting production unless there is a deliberate, documented environment split.

3. Local And Live Can Disagree For Real Reasons

Evidence: ForgeBoard health checks run in both local dev and production, and their observed lights have differed in the past. Local may have Doppler-backed secrets, dev-server CORS behavior, or fresh code before Vercel deploys; live has Vercel environment variables, CDN/cache, and deployed bundle timing. Plain pnpm dev without Doppler is truthful but not production-comparable: it can show provider credentials as missing and make all app-card lights unknown.

Why it is goofy: A green local board does not prove the live board is green, and a red local board does not always prove live production is broken.

Cleanup target: add a first-class local-vs-live comparison surface or script that reads the same UI-owned contracts from both pages: version, goal progress, service summary counts, and app blocker list. Treat disagreement as a bug to investigate, not a UI state to smooth over.

4. Local Vite Middleware Drifted From The Production API

Evidence: live ForgeBoard made one /api/cloudflare-domain-status?hostnames=... request, but local ForgeBoard made one failed bulk request followed by 52 single /api/cloudflare-domain-status?hostname=... fallback requests.

Why it is goofy: local and production were checking different API contracts for the same service light. That makes local Sentry/performance behavior noisier than production and can make local health evidence look worse or different for the wrong reason.

Cleanup target: keep Vite dev middleware and Vercel API handlers sharing the same route contracts. This instance is fixed in code and verified locally after a Doppler-backed restart; keep the regression test in place.

5. Sentry Org And Project Issue Queries Can Temporarily Disagree

Evidence: the live ForgeBoard org proxy omitted the then-dashboard project from countsBySlug at 2026-07-02 08:31 UTC, while direct project issue queries still returned DASHBOARD-B and DASHBOARD-D as unresolved/regressed. A later event-sample check showed those were stale local-development performance transactions, and after resolving them the direct project query and org proxy both showed no open ForgeBoard issues. Later the inverse happened: direct Sentry org/project queries showed 0 unresolved issues, while ForgeBoard's serverless proxy still served a cached 09:24 UTC payload listing four already resolved project issue counts.

Why it is goofy: ForgeBoard currently uses the org-level issue endpoint as its app-card source of truth. If the project-level endpoint can show open issues that the org-level endpoint omits, ForgeBoard can incorrectly make an app look greener than Sentry itself does.

Cleanup target: choose and document one issue-count source of truth, then make ForgeBoard surface the endpoint, query, fetched-at time, cache age, and any disagreement. Do not mark Sentry green from only the friendlier endpoint, but also do not let stale cached counts masquerade as fresh Sentry truth.

6. Vercel Ignore Commands Depend On Git Metadata

Evidence: Vercel ignoreCommand uses git diff, so excluding /.git/ from .vercelignore broke live ignore checks. The root ignore checker now guards against this.

Why it is goofy: The deploy package and deploy skip logic were fighting each other. Vercel needed Git metadata to decide what not to build.

Cleanup target: keep the guard, add a short Vercel operations note, and consider an explicit test that fails if any future ignore rule removes files required by build-time imports or skip logic.

7. Bulk Sentry Session Queries Return A Truncated Project Slice

Evidence: a one-request Sentry release-health query for all 52 project IDs returned only 13 groups, while individual and chunked project queries returned 26 projects with sum(session) > 0. Examples: example, dopples, and chetan each had counted sessions when queried directly, but were missing from the all-project response.

Why it is goofy: ForgeBoard treated absence from the bulk response as zero sessions, so it reported healthy browser-session apps as yellow. That violated the "tell the truth first" rule in the pessimistic direction: the board was not hiding failures, but it was inventing blockers from a lossy aggregation call.

Cleanup status: fixed in ForgeBoard v2026.07.02.14. The Sentry org proxy now queries session counts in small project chunks and only fills a project with zero after that project's chunk was actually checked. Keep the regression test so the proxy cannot return to one all-project request.

8. Many Vercel Projects Are Not Git-Linked

Evidence: GitHub push did not trigger several ForgeApps Vercel projects because their Vercel project link metadata is null. CLI Git connection requires an account with a GitHub login connection.

Why it is goofy: The stated deployment path is git push only, but some projects cannot be deployed by that path until their Vercel Git integration is connected.

Cleanup target: create an authoritative Vercel Git-link inventory in ForgeBoard and separate project-link blockers from app health. The fix likely requires Adam in the Vercel UI unless an automation token gains the required GitHub login connection.

Cleanup status: fixed for the current Sentry zero-session blocker set on 2026-07-02. The affected Vercel projects are now linked to adamkane/forgeapps on main, and the remaining oddball forgebrief app now has the standard repo-local Vercel config with the shared ignore command.

9. Sentry Green Requires Both Error Proof And Browser Sessions

Evidence: ForgeBoard treats a wired Sentry project as green only when it has captured event proof, recent browser sessions, and zero unresolved issues.

Why it is goofy: A project can be correctly wired and still yellow because no real browser session has arrived recently. That is correct for truthfulness, but the UI should make the distinction obvious so we do not mistake "needs a real production visit" for "SDK missing."

Cleanup target: split Sentry blocker copy into categories: missing project, missing repo wiring, missing captured event, missing recent browser sessions, and unresolved issues. Add counts per category to the Sentry setup page.

10. Static Sentry Hookup Apps Confuse Naive Scanners

Evidence: dopples, forgedesign, and webgl use scripts/static-sentry-hookup.ts through app-local build scripts. Their src/config/sentry.ts files export StaticSentryConfig and do not literally contain browserSessionIntegration, replay setup, release setup, or VITE_SENTRY_* env var reads.

Why it is goofy: a simple grep-style scanner says these apps are missing common Sentry browser-session wiring, while the static build hook actually renders the session/replay/release setup into production HTML.

Cleanup target: teach ForgeBoard's Sentry config tests to classify both Vite SDK apps and static-hookup apps through their real build path. If the static path remains supported, make it first-class in the tests instead of adding per-app exceptions.

11. Live Production Can Expose App Bugs During Health Probes

Evidence: the production-visit sweep loaded every target URL, but some pages rendered visible application failures unrelated to ForgeBoard's own health logic: forgecal JSON parsing, scifi library fetch, forgebuild load state, and headless WebGL context failures in experience, forgewatch, and glassware-viewer.

Why it is goofy: ForgeBoard can show infrastructure lights as green while a user-facing app page visibly fails. The current five-light model catches service readiness, not full app workflow health.

Cleanup target: add a separate production smoke-test lane that captures page load, console errors, and a minimal route-specific assertion for each app. Keep that lane distinct from the five service lights so the board stays truthful about what each signal means.

Cleanup status: partially improved on 2026-07-02. @forgeapps/ui now has a shared WebGL availability guard, and experience, forgewatch, and glassware-viewer use it on the routes that produced the Sentry issues. The broader production smoke-test lane is still open.

12. Greenlight History Filter Hid Real Progress

Evidence: GreenlightTrendChart rejected any recent point above 35% as a false high. Direct chunked Sentry session queries showed 50% browser-session proof while the stored chart still only showed lower stale values.

Why it is goofy: a defensive historical-data filter became a truthfulness bug. Once the board can genuinely climb above 35%, deleting those points makes the trend chart contradict the goal card and the direct provider evidence.

Cleanup status: fixed on 2026-07-02. The chart now keeps high recent progress points and only rejects the narrow half-loaded case: 100% with a tiny card total.

13. Redeploy Build Warnings Hid Small Consistency Drift

Evidence: the 26-app filtered redeploy build on 2026-07-02 completed, but it surfaced two non-fatal warnings: kando had duplicate VITE_SUPABASE_FORGEAPPS_* keys in src/config/env.ts, and deepwiki's markdown table regex was scanned into Tailwind's generated CSS as a malformed class candidate.

Why it is goofy: successful builds can still carry drift that makes the app assembly-line less predictable. Duplicate env keys make the effective config harder to reason about, and source-scanned regex fragments make CSS output depend on parser implementation details instead of real UI classes.

Cleanup status: fixed on 2026-07-02. kando now has one ForgeApps Supabase env entry pair, and deepwiki uses explicit table-separator predicates instead of regex literals that Tailwind can misread. Focused kando typecheck/test/build and deepwiki test/build checks pass.

14. WebGL Vercel Ignore Rules Escaped the App Boundary

Evidence: the webgl production deployment for commit 8e60a834c failed before build. Vercel's build events showed pnpm install --no-frozen-lockfile could not resolve @forgeapps/ui@workspace:* while installing from the monorepo. The webgl app-local .vercelignore used broad Unity patterns such as *.meta and Packages that Vercel evaluated against the monorepo upload context, so the deployment context could diverge from the real workspace.

Why it is goofy: app-local deployment ignores should only remove that app's Unity source noise. They must never change whether shared workspace packages exist for sibling apps or the monorepo install graph.

Cleanup status: fixed on 2026-07-02. apps/webgl/.vercelignore now scopes Unity exclusions to apps/webgl/..., keeps apps/webgl/dist/Build deployable, and avoids root packages/ ambiguity.

15. Local Sentry Session Proxy Under-counted Compared to Production

Evidence: after ForgeBoard v2026.07.02.16 reached production, the live page showed 26 of 52 apps green while local dev showed 13 of 52. Service counts matched for GitHub, Vercel, Supabase, and Cloudflare; only Sentry differed. Production chunks Sentry release-health session requests by project ID, but the Vite dev proxy sent all projects in one request, so Sentry returned a partial group set and local marked real session evidence missing.

Why it is goofy: local and production were both querying live Sentry, but they used different request shapes. That made local look more broken than live even when provider evidence was the same.

Cleanup status: fixed on 2026-07-02. The Vite dev Sentry proxy now chunks session-count requests using the same 10-project batch size as the production API route, and vite.config.test.ts covers the chunking contract.

16. Registry Domain Typos Can Masquerade as Cloudflare Failures

Evidence: ForgeBoard showed one Cloudflare red app: forgebot. The registry listed https://foregbot.forgefx.dev, which did not resolve, while the real production domain https://forgebot.forgefx.dev returned 200 from Vercel.

Why it is goofy: the Cloudflare check was telling the truth about the configured hostname, but the configured hostname was a typo. A plain registry typo can look like provider failure unless the registry has a validation lane that catches near-miss app-name domains before they reach the dashboard.

Cleanup status: fixed on 2026-07-02. apps/apps-metadata.json now points forgebot at https://forgebot.forgefx.dev. Add a registry-domain validation check that compares app names, declared production URLs, aliases, DNS, and Vercel aliases before app-card health checks treat a hostname as the intended target.

17. Sentry Session Wiring Can Exist in Source While Production Lags

Evidence: after live production visits, Sentry moved from 26 yellow / 26 green to 46 green / 6 yellow. The remaining six apps (adamkane, ally, bofa, forgebot, forgecal, forgetask) have app-local Sentry config, production DSNs in Doppler, and browserSessionIntegration() in source. Their live bundles either emitted no Sentry traffic or emitted transactions without session envelopes, and the deployed assets did not consistently show release/version evidence.

Why it is goofy: source, secrets, deployed bundle content, and provider evidence can drift independently. A dashboard light should stay yellow when release-health sessions are missing, but the cleanup path should make the app pipeline cookie-cutter: current source, versioned release, production deploy, live page visit, then Sentry session proof.

Cleanup status: mostly fixed on 2026-07-02. The six lagging apps were bumped and redeployed from current source. Fresh visits to ally, bofa, forgebot, forgecal, and forgetask emitted browser-session envelopes and Sentry counted those sessions. adamkane.vercel.app also emitted valid adamkane@2026.07.02.6 browser-session envelopes, but the custom adamkane.com / www.adamkane.com domain still serves an older Vercel project outside the ForgeFX team's access.

18. Sentry Project Grouping Can Miss Real Release Sessions

Evidence: adamkane.vercel.app served the current ForgeApps bundle and posted Sentry type: "session" envelopes with release adamkane@2026.07.02.6 and environment production. Direct Sentry sessions queries grouped by release or environment returned sum(session)=2, but the same project queried with only groupBy=project returned no groups. ForgeBoard accepted that empty project-group response as sessionCount: 0, so the app stayed yellow even though release-health sessions existed.

Why it is goofy: Sentry sessions are real provider evidence, but the grouping shape in our proxy could discard them. This is the same class of issue as chunking: the service light was only as truthful as its aggregation query.

Cleanup status: fixed in ForgeBoard v2026.07.02.20. The Sentry org proxy now asks for both groupBy=project and groupBy=release, then sums all release groups per project id. It queries one project at a time because cross-project chunks can still return only the highest-volume release groups and hide lower-volume apps. Tests cover multiple release groups contributing to one project's session count and enforce the one-project request contract in both production and local dev.

19. AdamKane Custom Domain Is Outside The ForgeFX Vercel Project

Evidence: the ForgeFX Vercel project adamkane owns and serves https://adamkane.vercel.app, including the current 2026.07.02.6 Sentry release bundle. https://adamkane.com redirects to https://www.adamkane.com, and that host serves an older Vercel bundle with no ForgeApps Sentry traffic. The ForgeFX Vercel API token can read the adamkane project but gets 403 forbidden for adamkane.com and www.adamkane.com, which means those domains are controlled outside the ForgeFX team/project.

Why it is goofy: the ForgeBoard registry and app docs say the production URL is adamkane.com, while the deployable ForgeFX production alias is adamkane.vercel.app. Sentry can prove the ForgeFX app is healthy on the Vercel alias, but the app-card URL still points users at a different deployment.

Cleanup target: decide the real production target and make everything match. If adamkane.com is intended, move/attach the domain to the ForgeFX adamkane Vercel project or update DNS/provider ownership with Adam's approval. If the Vercel alias is the intended deploy target for ForgeApps, update the app registry, docs, canonical metadata, and health expectations together instead of silently treating one host's Sentry proof as another host's health.

Working Rules