> For the complete documentation index, see [llms.txt](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/docs/deployment-blockers.md). # Deployment Blockers Known issues that must be resolved or accepted before a production Cloudflare Workers deployment. Last updated: 2026-05-26 (Group 3 documentation audit) *** ## Critical (Must Resolve Before Deploy) ### B001: No Cloudflare Account Configured **Impact**: Production deployment is skipped until Cloudflare credentials are available. **Resolution**: Run `wrangler login` for local manual deploys, or configure `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` in GitHub Actions secrets. The deploy workflow builds and runs its quality gate without those secrets, then skips the Wrangler deploy step with a notice. **Owner**: Project maintainer. ### ~~B002: No CI/CD Pipeline~~ (RESOLVED) **Impact**: Manual-only deployments are error-prone and unrepeatable. **Resolution**: GitHub Actions workflows now run lint, format, typecheck, script typecheck, unit tests, coverage, E2E integration, build, bundle budget, audit, and deploy gates. **Owner**: Project maintainer. **Status**: Resolved. *** ## High (Should Resolve Before Public Release) ### ~~B003: Client JS Bundle Size Exceeds Historical 700 kB Gzip Target~~ (RESOLVED) **Impact**: Slow initial page load on mobile or constrained networks. **Resolution**: Current enforced budget is 1.6 MB total client JS gzip, 350 KB gzip per app chunk, 450 KB gzip per lazy vendor chunk, and 300 KB raw CSS. `bun run budget:check` and `bun run demo:budget:pages` pass under the current threshold after the budget was raised from the earlier 1.55 MB total JS gzip threshold on 2026-07-03. **Reference**: CONSIDERATIONS.md \[S01 R006]. **Status**: Resolved for the current CI budget. Keep the 3D vendor chunks on the performance watchlist. ### ~~B004: Large Image Assets (8 Assets Over 1 MB Each)~~ (RESOLVED) **Impact**: Increased Worker bundle size and slow asset delivery without a CDN cache. **Resolution**: Phase 01 converted oversized assets to compressed formats. Current `src/assets/` size is 3.4 MB. The largest committed raster is `src/assets/logos/openai-gpt5.png` at about 388 KB; logos are excluded from the 200 KB automated media check and kept under manual review. Non-logo assets are below the 200 KB enforced limit. **Reference**: CONSIDERATIONS.md \[S01 R006]. **Status**: Resolved under the current media policy. ### ~~B005: No LICENSE File~~ (RESOLVED) **Impact**: Legal terms for the imported starter-based codebase were undefined. Contributors and users had no explicit license posture. **Resolution**: Proprietary all-rights-reserved LICENSE file added at project root, with `package.json` marked `UNLICENSED` because AI OS is a closed project built on top of Jack Roberts' original Claude OS project. **Reference**: CONSIDERATIONS.md \[S01 R003]. **Status**: Resolved. *** ## Medium (Acceptable for Hackathon Demo) ### ~~B006: Claude OS Branding Remains in UI~~ (RESOLVED) **Impact**: The UI, routes, and helper docs still reference legacy starter names rather than the intended product identity. **Resolution**: Session 15/16 aligned the then-current Trend Finder hackathon surface. A later identity pass separated AI OS as the host app from Trend Finder as an extension and added legacy storage migration. **Status**: Resolved. ### ~~B007: Pre-Commit Hook Requires Manual Setup~~ (RESOLVED) **Impact**: Secret scan git hook is not auto-activated for new clones. **Resolution**: `scripts/postinstall.sh` activates `.githooks/` on `bun install`; `bun run setup` also wires hooks. Manual `git config --local core.hooksPath .githooks` remains a recovery path. **Reference**: CONSIDERATIONS.md \[S01 R002]. **Status**: Resolved. ### ~~B008: No Dependency Vulnerability Audit~~ (RESOLVED) **Impact**: 681 packages have not been scanned for known vulnerabilities. **Resolution**: `bun audit` ran clean (0 vulnerabilities) in Phase 00 Session 08 and confirmed at Phase 00 certification (Session 12). **Reference**: CONSIDERATIONS.md \[S01 R017]. **Status**: Resolved. *** ## Low (Track for Future) ### ~~B009: Rollback Procedure Was Undocumented~~ (RESOLVED) **Impact**: If a bad deploy ships, rollback is manual via the Cloudflare dashboard or `bunx wrangler rollback`. **Resolution**: `docs/deployment.md` now records the Wrangler deployment-history rollback procedure, production `/health` verification, Cloudflare dashboard fallback, and failure issue requirements. Rollback remains operator-triggered because Cloudflare credentials and production deployment selection are manual release responsibilities. **Status**: Resolved. ### B010: Vite Preview Incompatible with Cloudflare Worker Build **Impact**: `bun run preview` fails with `ERR_MODULE_NOT_FOUND: dist/server/server.js`. TanStack Start's preview plugin expects `server.js` but the Cloudflare vite plugin produces `index.js`. **Resolution**: Use Wrangler local dev against the generated Worker config for local preview of the built Worker. Consider filing upstream with `@tanstack/start-plugin-core` or `@cloudflare/vite-plugin` for preview compatibility. **Workaround**: Run `bun run worker:preview` for full SSR preview at `http://127.0.0.1:8788` with the package-pinned Wrangler version. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/docs/deployment-blockers.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.