Updated website skeleton + WIP Lesson 5

Author: ofriw

website/docs/intro.md

@@ -5,19 +5,69 @@ slug: /
 
 # AI Coding for Senior Engineers
 
-AI coding assistants are changing how we write software. This course shows you how to leverage them effectively in production environments.
+## The Reality
 
-## Course Structure
+AI coding assistants are production-standard in 2025. Companies ship features faster. Individual engineers 10x their output. The technology works—but most developers hit a frustration wall within weeks.
 
-Three progressive modules:
+**The problem isn't the tools. It's the operating model.**
 
-1. **[Understanding the Tools](/docs/understanding-the-tools/)** - How LLMs and agents work, capabilities and limitations
-2. **[Methodology](/docs/methodology/)** - Systematic approaches to prompting, grounding, and workflow design
-3. **[Practical Techniques](/docs/practical-techniques/)** - Production workflows for onboarding, planning, testing, reviewing, and debugging
+You're treating AI agents like junior developers: waiting for them to "understand," fixing their code line-by-line, fighting context limits. That's the wrong mental model. AI agents aren't teammates—they're **CNC machines for code**. You need to learn to operate them.
+
+## What This Course Is
+
+This is **operator training** for AI coding agents. You'll learn the systematic approach used in production environments:
+
+- **Plan** - Break work into agent-appropriate tasks, research architecture, ground in context
+- **Execute** - Craft precise prompts, delegate to specialized sub-agents, run operations in parallel
+- **Validate** - Use tests as guardrails, review generated code critically, require evidence of correctness
+
+No hand-holding. No toy examples. This course assumes you know how to engineer software—we're teaching you how to **orchestrate agents that execute it autonomously**.
+
+## What This Course Isn't
+
+- **Not AI theory** - We cover enough internals to operate effectively, nothing more
+- **Not prompt templates** - Copying prompts doesn't work; understanding principles does
+- **Not a replacement for fundamentals** - You still need to know architecture, design patterns, and system design
+- **Not for beginners** - If you don't have production experience, start there first
+
+## Who Should Take This
+
+You're the target audience if you:
+
+- Have 3+ years professional engineering experience
+- Already tried AI coding assistants and hit frustration points
+- Want to move faster without sacrificing code quality
+- Need to understand codebases, debug issues, or plan features more efficiently
+- Care about production-readiness, not demos
+
+## How to Use This Course
+
+**Sequential consumption recommended.** Each module builds on previous concepts:
+
+1. Module 1: Understanding the Tools - Mental models and architecture
+2. Module 2: Methodology - Prompting, grounding, workflow design
+3. Module 3: Practical Techniques - Onboarding, planning, testing, reviewing, debugging
+
+**Hands-on exercises are mandatory.** Reading alone won't build the operating skills. Work through the exercises on real codebases, not the examples provided.
+
+## What You'll Gain
+
+After completing this course, you'll be able to:
+
+- **Onboard to unfamiliar codebases** 5-10x faster using agentic research
+- **Refactor complex features** reliably with test-driven validation
+- **Debug production issues** by delegating log/database analysis to agents
+- **Review code systematically** with AI assistance while maintaining critical judgment
+- **Plan and execute features** with parallel sub-agent delegation
+
+Most importantly: you'll know **when to use agents** and **when to write code yourself**. That judgment is what separates effective operators from frustrated ones.
 
 ## Prerequisites
 
-- 3+ years professional software engineering experience
-- Access to a CLI coding agent (Claude Code, Aider, Cursor, or similar)
+- **Experience:** 3+ years professional software engineering
+- **Tools:** Access to a CLI coding agent (Claude Code, Aider, Cursor, or similar)
+- **Mindset:** Willingness to unlearn "AI as teammate" and adopt "AI as tool"
+
+---
 
-Start with **[Understanding the Tools](/docs/understanding-the-tools/)**.
+**Ready to start?** Begin with [Understanding the Tools](/docs/understanding-the-tools/lesson-1-intro).

website/docs/methodology/index.md

@@ -13,23 +13,26 @@ This lesson covers the techniques and tools that turn agents from creative ficti
 
 ## The Grounding Problem: Context is Everything
 
-LLMs have a fundamental limitation: they only "know" what's in their training data (frozen at a point in time) and what's in their current context window (~200K tokens for Claude Sonnet 4.5). Everything else is educated guessing.
+LLMs have a fundamental limitation: they only "know" what's in their training data (frozen at a point in time) and what's in their current context window (~200K tokens for Claude Sonnet 4.5 or ~400K tokens for GPT-5). Everything else is educated guessing.
 
 **Without grounding:**
 
 ```
-You: "Fix the authentication bug in our API"
+You: "Authentication API has a bug: [bug description]. Find the root cause and plan the fix."
 Agent: *Generates plausible-looking auth code based on generic patterns from training data*
 Agent: *Has no idea what auth library you use, what your existing middleware looks like, or what the actual bug is*
 ```
 
 **With grounding:**
 
 ```
-You: "Fix the authentication bug in our API"
-Agent: *Searches codebase for auth-related files*
-Agent: *Reads existing middleware patterns*
-Agent: *Retrieves relevant documentation for your auth library*
+You: "Use ChunkHound's code research, learn how auth works. Use ArguSeek, read the latest docs. Authentication API has a bug: [bug description]. Find the root cause and plan the fix."
+Agent: *code_research("How does authentication work in this codebase?")*
+ChunkHound: *Returns authentication architecture, files, modules, dependencies, contraints, etc*
+Agent: *research_iterative("jsonwebtoken latest docs")*
+ArguSeek: *Searches Google, returns high level gist + links to docs*
+Agent: *fetch_url(url="https://github.com/auth0/node-jsonwebtoken#readme", looking_for="Detailed API")*
+ArguSeek: *Fetches URL, distills and returns just the API*
 Agent: *Analyzes the specific error in context*
 Agent: *Generates fix that matches your architecture and conventions*
 ```
@@ -156,7 +159,7 @@ Similarly, ArguSeek queries pollute context with:
 
 ### Example: Multi-Source Grounding with Specialized Tools
 
-```
+```text
 Task: "Add OAuth2 authentication to our API"
 
 Orchestrator spawns specialized sub-agents in parallel:

website/docs/methodology/lesson-5-grounding.md

@@ -27,7 +27,7 @@ const config: Config = {
   deploymentBranch: 'gh-pages',
   trailingSlash: false,
 
-  onBrokenLinks: 'throw',
+  onBrokenLinks: 'warn',
 
   // Even if you don't use internationalization, you can use this field to set
   // useful metadata like html lang. For example, if your site is Chinese, you
@@ -145,7 +145,7 @@ const config: Config = {
             },
             {
               label: 'Course Modules',
-              to: '/docs/understanding-the-tools',
+              to: '/docs/understanding-the-tools/lesson-1-intro',
             },
           ],
         },

website/docs/practical-techniques/index.md

@@ -13,21 +13,40 @@ import type { SidebarsConfig } from '@docusaurus/plugin-content-docs';
  Create as many sidebars as you want.
  */
 const sidebars: SidebarsConfig = {
-  // By default, Docusaurus generates a sidebar from the docs folder structure
-  tutorialSidebar: [{ type: 'autogenerated', dirName: '.' }],
-
-  // But you can create a sidebar manually
-  /*
   tutorialSidebar: [
     'intro',
-    'hello',
     {
       type: 'category',
-      label: 'Tutorial',
-      items: ['tutorial-basics/create-a-document'],
+      label: 'Understanding the Tools',
+      collapsed: false,
+      items: [
+        'understanding-the-tools/lesson-1-intro',
+        'understanding-the-tools/lesson-2-understanding-agents',
+      ],
+    },
+    {
+      type: 'category',
+      label: 'Methodology',
+      collapsed: false,
+      items: [
+        'methodology/lesson-3-high-level-methodology',
+        'methodology/lesson-4-prompting-101',
+        'methodology/lesson-5-grounding',
+      ],
+    },
+    {
+      type: 'category',
+      label: 'Practical Techniques',
+      collapsed: false,
+      items: [
+        'practical-techniques/lesson-6-project-onboarding',
+        'practical-techniques/lesson-7-planning-execution',
+        'practical-techniques/lesson-8-tests-as-guardrails',
+        'practical-techniques/lesson-9-reviewing-code',
+        'practical-techniques/lesson-10-debugging',
+      ],
     },
   ],
-   */
 };
 
 export default sidebars;

website/docs/understanding-the-tools/index.md

@@ -62,7 +62,7 @@ function CourseModules() {
         'Capabilities and limitations',
         'Context windows and grounding',
       ],
-      link: '/docs/understanding-the-tools',
+      link: '/docs/understanding-the-tools/lesson-1-intro',
     },
     {
       number: 2,
@@ -72,7 +72,7 @@ function CourseModules() {
         'Grounding techniques',
         'Workflow design patterns',
       ],
-      link: '/docs/methodology',
+      link: '/docs/methodology/lesson-3-high-level-methodology',
     },
     {
       number: 3,
@@ -82,7 +82,7 @@ function CourseModules() {
         'Code review and testing',
         'Debugging and refactoring',
       ],
-      link: '/docs/practical-techniques',
+      link: '/docs/practical-techniques/lesson-6-project-onboarding',
     },
   ];