Next Steps Plan – November 2025
This document groups the recommended follow-up work into focused initiatives so we can spread effort across two or more branches without stepping on each other. Each initiative lists the concrete tasks, expected leverage, and coordination notes.
---
1. Platform Hygiene & Build Reliability
Focus: make builds deterministic and keep the repo source-only so CI and Vercel behave the same way locally.| Task | Why it matters | Scope & Notes | Suggested Branch |
| --- | --- | --- | --- |
| Unify Next.js config (next.config.ts, next.config.mjs) | Currently two configs disagree (PPR enabled vs disabled, lint/type checks on/off). Which file Vercel picks depends on extension order, so prod can silently diverge from local dev. | Choose one config format (likely the typed .ts), port any extra headers from the .mjs, make an explicit call on PPR, and ensure CI/deploy paths import the same file. Update docs/README to mention the chosen experimental flags. | chore/next-config-unify |
| Remove committed build artifacts (lib/generation/*.js, packages/cli/dist) | Generated JS drifts from TS sources and causes noisy diffs / accidental edits. Keeping artifacts out of git clarifies the source of truth and shrinks PRs. | Delete checked-in bundles, add their paths to .gitignore, and document build commands for contributors (e.g., pnpm --filter @weldr/cli build). Verify CI builds packages before publishing. | chore/remove-built-artifacts |
| Modernize lint/test scripts (package.json) | pnpm lint currently mutates files (--write --unsafe) and test:unit chains dozens of node --import invocations. That makes CI non-deterministic and discourages devs from running tests locally. | Split lint scripts into lint (read-only) and lint:fix. Replace the chained node --import script with a Vitest (or tsx --test) runner that can be filtered/watched. Ensure CI uses the read-only version. | chore/devtooling-upgrade |
chore/next-config-unify separately so Vercel/testing changes aren’t blocked by the artifact cleanup, which can live in chore/remove-built-artifacts. The dev-tooling update can merge after those land to avoid rebasing on moved config files.
---
2. Runtime Experience & Documentation Alignment
Focus: ensure what we ship (iframe/WebContainer preview) matches what the docs describe, and keep internal harnesses out of production routes.| Task | Why it matters | Scope & Notes | Suggested Branch |
| --- | --- | --- | --- |
| Gate or relocate /app/test-* routes (app/test-preview, etc.) | Internal harness pages currently deploy with marketing/production pages, creating attack surface and extra bundle weight. | Move these routes under a (tests) group, protect them with middleware that checks NODE_ENV or a feature flag, or convert them into Playwright fixtures. Update biome.jsonc ignores once their location changes. | feat/runtime-test-sandbox |
| Consolidate runtime docs (docs/architecture/ir-runtime.md, docs/DOCUMENTATION_AUDIT_2025-10-13.md) | The architecture docs still describe UIRuntimeProvider, but the shipped experience is the iframe/WebContainer flow (app/embed/runtime/.../runtime-client.tsx). This mismatch confuses readers and was already flagged in the doc audit. | Write a single canonical “Runtime Architecture” doc describing the current preview clients, API endpoints, and IR snapshot usage. Archive or link out old progress logs. Update README / docs index to point to the new guide. | docs/runtime-refresh |
---
3. Lint & Developer Ergonomics
Focus: eliminate known warnings so CI stays clean and devs trust lint output.| Task | Why it matters | Scope & Notes | Suggested Branch |
| --- | --- | --- | --- |
| Finish the lint cleanup plan (docs/maintenance/lint-cleanup-plan.md) | ESLint currently emits three warnings (Tailwind shorthand, two useMemo deps). Leaving them unresolved encourages eslint-disable sprawl and hides future issues. | Apply the plan: change h-full w-full → size-full in app/(chat)/chat/[id]/page.tsx, refactor components/code-generation-panel.tsx memo dependencies, and wrap the DSL memo in components/app-model-editor.tsx. Re-run pnpm lint (read-only version after the tooling update) to confirm a clean slate. | chore/lint-cleanup |
This branch is largely self-contained (only three files) and can merge in parallel with either of the two initiatives above. Once merged, update the lint plan doc to reflect the cleared warnings.
---
Suggested Sequencing
Splitting along these initiatives gives us at least two parallel work streams (platform vs runtime/docs), with the lint cleanup as a quick win that can merge independently.