Bowen/UI improvements

README.md

@@ -1,53 +1,65 @@
 # Forge
 
-**Forge** is an AI-based onboarding platform that turns a production codebase into a sequenced, modular learning experience—like "lego blocks" in an interactive walkthrough. Instead of reading scattered docs or relying on tribal knowledge, developers progress through blocks that explain a system's modules, dependencies, and intent, with contextual file navigation and AI assistance.
+**Forge** is an AI-powered onboarding platform that turns a codebase into a guided, step-by-step learning experience — like building with lego blocks in an interactive walkthrough. Instead of reading scattered docs or relying on knowledge that only lives in people's heads, developers progress through bite-sized blocks that explain how a system is built, how its pieces connect, and why things work the way they do — with built-in code navigation and AI assistance.
 
 *Built for the 10,000 AIdeas (AWS) competition.*
 
 ---
 
 ## What it's about
 
-New engineers often spend weeks onboarding through linear, unstructured documentation and tribal knowledge. That leads to slow time-to-first-contribution, heavy dependence on senior engineers, and knowledge loss when experienced teammates leave. AI-assisted development can also encourage "vibe coding"—shipping code without understanding *why* it works—which increases bugs and risk. Forge addresses this with a **pedagogy-first** tool that focuses on understanding: it converts a repository into an interactive storyboard that teaches the system step-by-step, with each block explained in context by AI and linked directly to real code.
+New engineers often spend weeks onboarding through messy documentation and unwritten knowledge passed down by word of mouth. That leads to a slow ramp-up, heavy dependence on senior engineers, and knowledge gaps when experienced teammates leave. AI-assisted development can also encourage "vibe coding" — shipping code without understanding *why* it works — which increases bugs and risk. Forge addresses this with a **learning-first** tool that focuses on real understanding: it turns a repository into an interactive storyboard that teaches the system step-by-step, with each block explained by AI and linked directly to the actual code.
 
 ---
 
 ## What it does
 
-- **Ingest a repo** — Point Forge at a Git URL. It clones the repo, stores files, and (for the same public GitHub commit) can reuse an existing parsed build so you don't wait twice.
-- **Parse & structure** — A parser builds a module and dependency graph (AST-style) so the system understands how the codebase is organized.
-- **Generate a storyboard** — AI (Amazon Bedrock) produces 5–10 ordered "blocks": each has a learning objective, explanation, key files, key symbols, Mermaid diagrams, and suggested questions. Blocks are grounded in the actual repo, not generic advice.
-- **Walk through & explore** — A VS Code–style workspace: file explorer, read-only code view, and a storyboard panel. You move through blocks in order (or jump), open linked files, and see diagrams and explanations in one place.
-- **Chat in context** — For each block, you can ask questions in a **block-scoped** chat. The AI is constrained to that block and its dependencies, so answers stay grounded in the code and reduce hallucinations.
-- **Role-based paths** — Choose a path (frontend, backend, infra, full-stack). The storyboard order and emphasis adapt so you see what's relevant to your role first.
-- **Track progress** — Completion per block and time-on-block are tracked so you (and onboarding owners) can see how far someone's gotten and where they might be stuck.
+- **Import a repo** — Point Forge at a GitHub link. It downloads the repo, stores the files, and can reuse a previous analysis of the same version so you don't wait twice.
 
-Ingest, parse, and storyboard generation run **asynchronously**: you can enter the workspace quickly; cloning, parsing, and AI generation continue in the background while you browse files. The UI shows pipeline state (cloning → parsing → storyboard → ready) and stays usable throughout.
+- **Analyze & organize** — Forge automatically maps out the codebase's structure — its folders, files, and how different pieces depend on each other — so it understands how everything fits together.
+
+- **Generate a storyboard** — AI produces 5–10 ordered "blocks," each with a learning goal, a plain-language explanation, the key files involved, visual diagrams, and suggested questions. Every block is grounded in the actual code, not generic advice.
+
+- **Walk through & explore** — A code-editor-style workspace with a file browser, a read-only code viewer, and a storyboard panel. You move through blocks in order (or jump around), open the referenced files, and see diagrams and explanations all in one place.
+
+- **Chat in context** — For each block, you can ask questions in a focused chat. The AI only has access to that block's scope and related code, so answers stay accurate and relevant.
+
+- **Role-based paths** — Choose a learning path (frontend, backend, infrastructure, or full-stack). The storyboard reorders and adjusts emphasis so you see what matters most for your role first.
+
+- **Track progress** — Completion and time spent per block are tracked, so you (and whoever manages onboarding) can see how far someone has gotten and where they might be stuck.
+
+Import, analysis, and storyboard generation all happen **in the background**: you can start exploring the workspace right away while Forge finishes processing. The UI shows the current stage (downloading → analyzing → generating storyboard → ready) and stays usable throughout.
 
 ---
 
 ## Who it's for
 
-- **New hires & junior engineers** — A guided mental model of the system and safe, contextual Q&A instead of ad-hoc docs.
-- **Cross-functional engineers** — A curated path that skips irrelevant depth and highlights the interfaces that matter.
-- **Tech leads & onboarding owners** — Reusable onboarding assets and less repetitive mentoring.
-- **Distributed teams** — Asynchronous onboarding that preserves architectural intent and stays in sync with the repo.
+- **New hires & junior engineers** — A guided tour of the system with safe, focused Q&A instead of scattered docs.
+
+- **Engineers switching teams** — A tailored path that skips what you don't need and highlights the parts that matter for your role.
+
+- **Tech leads & onboarding owners** — Reusable onboarding content and less time spent answering the same questions.
+
+- **Distributed teams** — Self-serve onboarding that captures how the system is designed and stays up to date with the repo.
 
 ---
 
 ## Goals
 
-- **Reduce onboarding time** by producing a structured, accurate learning path derived directly from the repository.
-- **Increase comprehension and confidence** via block-scoped AI chat grounded in the current module and its dependencies.
-- **Support role-based paths** (frontend, backend, infra, full-stack) so engineers see what's relevant first.
-- **Stay cost-conscious for MVP** with serverless AWS, caching, and on-demand usage (e.g. Bedrock).
+- **Reduce onboarding time** by generating a structured, accurate learning path directly from the repository.
+
+- **Increase comprehension and confidence** through focused AI chat that's grounded in the code you're learning about.
+
+- **Support role-based paths** (frontend, backend, infrastructure, full-stack) so engineers see what's relevant first.
+
+- **Stay cost-conscious** with serverless cloud infrastructure, caching, and pay-as-you-go AI usage.
 
 ---
 
 ## Tech at a glance
 
-- **Frontend:** Next.js 16, React 19, TypeScript — VS Code–style layout (file tree, editor, storyboard + chat panel).
-- **Backend:** AWS SAM — API Gateway, Lambda (Node.js 20), DynamoDB, S3, Amazon Bedrock (Nova 2 Lite). Parsing uses tree-sitter; storyboard and chat use Bedrock with constrained context.
+- **Frontend:** Next.js 16, React 19, TypeScript — a code-editor-style layout with a file tree, code viewer, and storyboard + chat panel.
+- **Backend:** AWS (serverless) — API Gateway, Lambda, DynamoDB, S3, and Amazon Bedrock for AI. Code analysis uses tree-sitter; storyboard and chat are powered by Bedrock with focused context windows.
 
 For **setup, run, and deploy** instructions, see [backend/README.md](backend/README.md) and [frontend/README.md](frontend/README.md). Repo layout: `frontend/` (Next.js app), `backend/` (SAM template + Lambda handlers), and [PRD/Forge_PRD.md](PRD/Forge_PRD.md) for the full product requirements document.
 

frontend/src/app/(workspace)/workspace/[repoId]/page.tsx

@@ -1564,6 +1564,12 @@ function StoryboardPanel({
     onGoPrev: () => void;
     onGoNext: () => void;
 }) {
+
+    const scrollableRef = useRef<HTMLDivElement>(null);
+
+    useEffect(() => {
+        scrollableRef.current?.scrollTo(0, 0);
+    }, [activeBlock]);
     if (blocks.length === 0) {
         return (
             <div className="empty-state" style={{ height: '100%' }}>
@@ -1596,7 +1602,7 @@ function StoryboardPanel({
             </div>
 
             {/* ── Scrollable Content ── */}
-            <div className="block-detail-scrollable">
+            <div className="block-detail-scrollable" ref={scrollableRef}>
                 {nextBlockLocked && (
                     <div className="sequential-hint">
                         <Codicon name="lock" />