docs: update README, changelog, and architecture for v7 deploy polish

Author: wai-coding

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## v7 — Deploy Polish and Browser Separation
+
+- Improved browser bundle architecture with a separate browser-safe entry point and lazy-loaded analysis engine
+- Pinned Node engine to 20.x for stable Vercel deployments
+- Strengthened rule-system alignment tests to prevent drift between rule registry, config defaults, and presets
+- Polished web app onboarding with clearer browser capability fallback and step-by-step instructions
+- Removed vague phrasing from export summary templates and added stricter bullet validation
+
 ## v6 — Conservative Rule Expansion
 
 - Added 5 new conservative analysis rules: `no-console`, `no-empty-function`, `duplicate-imports`, `no-unreachable-after-return`, `no-throw-literal`

README.md

@@ -47,6 +47,8 @@ Manual code review is time-consuming and inconsistent. InspectoRepo provides det
 | Analysis | ts-morph (TypeScript AST) |
 | Testing  | Vitest                    |
 | Monorepo | npm workspaces            |
+| Node     | 20.x                      |
+| Deploy   | Vercel (Preview)          |
 
 ## Project Structure
 
@@ -99,6 +101,12 @@ npm test
 
 > **Export packs:** `npm run repopack` generates four versioned files under `ai/exports/`. Use `repo-pack-latest-vN.md` for a quick lightweight review — it includes project structure and core source without docs, screenshots, or scripts.
 
+## Deployment
+
+The web UI is deployed on Vercel as a **Preview** build. It runs the same analysis engine as the CLI — ts-morph executes entirely in the browser via an in-memory file system.
+
+> **Browser note:** Folder selection requires the File System Access API (Chrome/Edge). Other browsers can use the Upload Folder fallback. The analysis engine (ts-morph) is lazy-loaded to keep the initial page load fast.
+
 ## Demo
 
 Try InspectoRepo locally in three steps:

docs/agent-worklog.md

@@ -4,6 +4,41 @@ Development log for InspectoRepo. Each entry describes what was implemented, why
 
 ---
 
+## 2026-03-11 — V7: Deploy Polish and Browser Separation
+
+### What was implemented
+
+- **Browser-safe entry point** — new `packages/core/src/browser.ts` re-exports only lightweight utilities (file-filter, scanner, scoring, report, config, presets) with zero ts-morph dependency. Web app imports from `@inspectorepo/core/browser` for initial load; heavy analysis is lazy-loaded via dynamic `import('@inspectorepo/core')` only when the user clicks Analyze.
+- **Package exports field** — `packages/core/package.json` now declares `"exports": { ".": "./dist/index.js", "./browser": "./dist/browser.js" }` so bundlers can tree-shake correctly.
+- **Vite build target** — `apps/web/vite.config.ts` sets `build.target: 'es2022'` and uses `manualChunks` to isolate ts-morph into a separate `analysis-engine` chunk.
+- **Node engine pin** — root `package.json` changed `engines.node` from `>=20.0.0` to `20.x` to match CI and Vercel runtime.
+- **Rule-system alignment tests** — `config.test.ts` now derives `ALL_RULE_IDS` dynamically from `allRules` instead of a hardcoded list. Added 7 new tests: every rule in DEFAULT_CONFIG, no unknown rules in config, presets reference only known IDs, presets cover every rule, filterRulesByConfig consistency, no duplicate IDs, count match.
+- **Web app onboarding polish** — `MainPanel.tsx` improved with ordered step list, browser compatibility warning, sample project hint, and checkmark icon in empty state.
+- **Export summary hardening** — `generate-repomix-exports.ts` replaces vague area bullet templates and adds `VAGUE_BANNED_PHRASES` regex array to `isQualityBullet()`.
+- **README and CHANGELOG** — added Node 20.x / Vercel rows to tech stack, new Deployment section, and v7 changelog entry.
+
+### Why
+
+After the first successful Vercel deploy, the web app pulled the entire ts-morph library (~2 MB) into the initial bundle via barrel imports. Separating browser-safe utilities from the heavy analysis engine reduces initial load time significantly. The Node engine pin and rule alignment tests harden the project for CI and prevent future drift.
+
+### How to verify
+
+```bash
+npm run lint
+npm run typecheck
+npm run build
+npm test
+```
+
+### Design decisions
+
+- **Separate entry point over conditional exports** — a dedicated `browser.ts` file is clearer than `"browser"` condition maps and works with all bundlers.
+- **Lazy `import()` over eager import** — the analysis engine (ts-morph) is only needed when the user clicks Analyze. Dynamic import keeps initial page load fast.
+- **`20.x` over `>=20`** — pins to Node 20 LTS to match Vercel default and CI matrix, avoiding surprises from Node 22+ changes.
+- **Derived rule IDs** — `allRules.map(r => r.id)` eliminates the need to update a hardcoded list when adding new rules.
+
+---
+
 ## 2026-03-11 — Richer Analysis Rules and Export Polish
 
 ### What was implemented

docs/architecture-and-rules.md

@@ -7,6 +7,7 @@
 ```
 packages/core/src/
 ├── index.ts              # Public API: analyzeCodebase, buildMarkdownReport, re-exports
+├── browser.ts            # Browser-safe API: lightweight re-exports without ts-morph
 ├── config.ts             # Rule configuration loader (.inspectorepo.json)
 ├── ignore.ts             # Ignore file loader (.inspectorepoignore)
 ├── scanner.ts            # isAnalyzableFile, filterAnalyzableFiles
@@ -30,6 +31,10 @@ packages/core/src/
 
 The core analysis engine never touches the filesystem. The public API accepts `VirtualFile[]` (`{ path: string; content: string }`). This keeps core importable from a browser bundle (the web app) without polyfilling Node's `fs`. Any filesystem access (directory picker, file reading) lives in `apps/web` or a future CLI adapter.
 
+**1b. Browser entry point separates heavy dependencies**
+
+`browser.ts` re-exports only lightweight utilities (file-filter, scanner, scoring, report, config, presets) with zero ts-morph dependency. The web app imports from `@inspectorepo/core/browser` for initial load. The heavy analysis engine (ts-morph) is lazy-loaded via `import('@inspectorepo/core')` only when the user triggers analysis. The `package.json` exports field maps `"./browser"` to `dist/browser.js`.
+
 **2. Filesystem adapters live outside core**
 
 `apps/web/src/folder-reader.ts` already handles File System Access API and `<input webkitdirectory>`. A future CLI package would use Node `fs` to produce the same `VirtualFile[]` shape. Core doesn't care where the bytes come from.

docs/code-walkthrough.md

@@ -189,6 +189,10 @@ The analysis engine. Parses files, runs rules, computes scores, generates report
 
 Public API surface: `analyzeCodebase`, `buildMarkdownReport`, `computeScore`, all rules, file-filter utilities, scanner.
 
+### `src/browser.ts`
+
+Browser-safe entry point with zero ts-morph dependency. Re-exports only lightweight utilities: file-filter (`isExcludedDir`, `buildDirectoryTree`, `filterExcludedPaths`, `pickDefaultDirs`, `filterBySelectedDirs`, `normalizeRelativePath`), types (`DirEntry`, `FileEntry`), scanner (`filterAnalyzableFiles`, `isAnalyzableFile`), scoring (`computeScore`), report (`buildMarkdownReport`, `buildHtmlReport`), report-parser (`parseReportSummary`), presets, and config types. The web app imports from `@inspectorepo/core/browser` for initial load to keep the bundle small. The heavy `analyzeCodebase` function (which depends on ts-morph) is lazy-loaded via `import('@inspectorepo/core')` only when the user clicks Analyze.
+
 ### `src/analyzer.ts`
 
 Main analysis pipeline entry point:
@@ -395,9 +399,9 @@ Both methods return `{ name, files: VirtualFile[] }` with actual file content po
 ### `src/useAppState.ts`
 
 Central state hook managing folder, files, dirs, report, and selected issue. Key functions:
-- `handleAnalyze` — calls `analyzeCodebase()` from core
+- `handleAnalyze` — lazy-loads `analyzeCodebase` from `@inspectorepo/core` via dynamic `import()` (keeping ts-morph out of the initial bundle), then runs analysis
 - `selectIssue` — sets the currently selected issue for the detail panel
-- `exportMarkdown` — calls `buildMarkdownReport()` and triggers browser download
+- `exportMarkdown` — calls `buildMarkdownReport()` (from the lightweight `@inspectorepo/core/browser` import) and triggers browser download
 
 ### `src/components/TopBar.tsx`