From 74dee5f9152cebe0390c16d48a63b5eb683f7307 Mon Sep 17 00:00:00 2001
From: lua-stefan-kruger <stefan@luaprompt.com>
Date: Mon, 23 Mar 2026 16:02:28 +0000
Subject: [PATCH] feat: add interactive Learn section with embedded terminal
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds a new "Learn" tab to the docs with an 18-lesson curriculum
across 3 tracks (Beginner, Intermediate, Professional).

Each lesson includes an embedded StackBlitz WebContainer terminal
where users can run real lua-cli commands interactively — no local
setup required.

First lesson (Authentication) is fully built with:
- Embedded terminal with lua-cli pre-installed
- Step-by-step instructions
- Knowledge check questions
- Navigation to next lesson

Remaining 17 lessons are placeholders to be filled in.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 docs.json                  | 38 ++++++++++++++++
 learn/authentication.mdx   | 92 ++++++++++++++++++++++++++++++++++++++
 learn/data-and-search.mdx  |  8 ++++
 learn/dynamic-jobs.mdx     |  8 ++++
 learn/ecommerce.mdx        |  8 ++++
 learn/full-project.mdx     |  8 ++++
 learn/integrations.mdx     |  8 ++++
 learn/mcp-servers.mdx      |  8 ++++
 learn/multi-channel.mdx    |  8 ++++
 learn/persona-design.mdx   |  8 ++++
 learn/processors.mdx       |  8 ++++
 learn/production-ops.mdx   |  8 ++++
 learn/push-and-deploy.mdx  |  8 ++++
 learn/scheduled-jobs.mdx   |  8 ++++
 learn/skills-and-tools.mdx |  8 ++++
 learn/testing.mdx          |  8 ++++
 learn/user-state.mdx       |  8 ++++
 learn/webhooks.mdx         |  8 ++++
 learn/your-first-agent.mdx |  8 ++++
 19 files changed, 266 insertions(+)
 create mode 100644 learn/authentication.mdx
 create mode 100644 learn/data-and-search.mdx
 create mode 100644 learn/dynamic-jobs.mdx
 create mode 100644 learn/ecommerce.mdx
 create mode 100644 learn/full-project.mdx
 create mode 100644 learn/integrations.mdx
 create mode 100644 learn/mcp-servers.mdx
 create mode 100644 learn/multi-channel.mdx
 create mode 100644 learn/persona-design.mdx
 create mode 100644 learn/processors.mdx
 create mode 100644 learn/production-ops.mdx
 create mode 100644 learn/push-and-deploy.mdx
 create mode 100644 learn/scheduled-jobs.mdx
 create mode 100644 learn/skills-and-tools.mdx
 create mode 100644 learn/testing.mdx
 create mode 100644 learn/user-state.mdx
 create mode 100644 learn/webhooks.mdx
 create mode 100644 learn/your-first-agent.mdx

diff --git a/docs.json b/docs.json
index 8783a85..c99bdde 100644
--- a/docs.json
+++ b/docs.json
@@ -14,6 +14,44 @@
   "favicon": "/favicon.png",
   "navigation": {
     "tabs": [
+      {
+        "tab": "Learn",
+        "groups": [
+          {
+            "group": "Beginner",
+            "pages": [
+              "learn/authentication",
+              "learn/your-first-agent",
+              "learn/skills-and-tools",
+              "learn/testing",
+              "learn/push-and-deploy",
+              "learn/persona-design"
+            ]
+          },
+          {
+            "group": "Intermediate",
+            "pages": [
+              "learn/user-state",
+              "learn/data-and-search",
+              "learn/webhooks",
+              "learn/scheduled-jobs",
+              "learn/processors",
+              "learn/integrations",
+              "learn/ecommerce"
+            ]
+          },
+          {
+            "group": "Professional",
+            "pages": [
+              "learn/mcp-servers",
+              "learn/multi-channel",
+              "learn/dynamic-jobs",
+              "learn/production-ops",
+              "learn/full-project"
+            ]
+          }
+        ]
+      },
       {
         "tab": "Overview",
         "groups": [
diff --git a/learn/authentication.mdx b/learn/authentication.mdx
new file mode 100644
index 0000000..27de513
--- /dev/null
+++ b/learn/authentication.mdx
@@ -0,0 +1,92 @@
+---
+title: "Lesson 1: Authentication"
+description: "Set up the Lua CLI and authenticate your account"
+---
+
+<Info>
+**Beginner** | 5 min | Lesson 1 of 18
+</Info>
+
+## What you'll learn
+
+- Run the Lua CLI
+- Authenticate your account interactively
+- Verify your setup works
+
+## Interactive Terminal
+
+Use the terminal below to follow along. `lua-cli` is pre-installed and ready to use.
+
+<iframe
+  src="https://stackblitz.com/edit/ssyfrbnq?embed=1&view=terminal&hideExplorer=1&hideNavigation=1"
+  allow="cross-origin-isolated"
+  style={{
+    width: '100%',
+    height: '400px',
+    border: '1px solid #2a2a2a',
+    borderRadius: '8px',
+    overflow: 'hidden'
+  }}
+/>
+
+## Step 1: Check the CLI
+
+The Lua CLI is pre-installed in the terminal above. Verify it's working:
+
+```bash
+lua --version
+```
+
+You should see the version number printed.
+
+## Step 2: Authenticate
+
+Run the authentication command — the CLI will guide you through the process interactively:
+
+```bash
+lua auth configure
+```
+
+The CLI will ask you to choose between:
+- **API Key** — paste your key when prompted
+- **Email OTP** — enter your email, check your inbox for the code, then enter it
+
+<Tip>
+**Don't have an API key?** No worries — choose the email option. The CLI will send a one-time code to your inbox.
+</Tip>
+
+## Step 3: Verify
+
+Once authenticated, check that everything is connected:
+
+```bash
+lua agents
+```
+
+You should see your organizations and agents listed. If you're brand new, the list may be empty — that's fine! We'll create an agent in the next lesson.
+
+## Knowledge Check
+
+<AccordionGroup>
+  <Accordion title="What command starts the authentication flow?">
+    `lua auth configure` — this launches the interactive authentication wizard where you choose between API key or email OTP.
+  </Accordion>
+  <Accordion title="What are the two ways to authenticate?">
+    1. **API Key** — if you already have one, paste it when prompted
+    2. **Email OTP** — the CLI sends a 6-digit code to your email
+  </Accordion>
+  <Accordion title="How do you verify authentication worked?">
+    Run `lua agents` to list your organizations and agents. If it returns results (or an empty list without errors), you're authenticated.
+  </Accordion>
+</AccordionGroup>
+
+## Next Steps
+
+<CardGroup cols={2}>
+  <Card title="Next: Your First Agent" icon="rocket" href="/learn/your-first-agent">
+    Create and configure your first AI agent
+  </Card>
+  <Card title="CLI Reference" icon="terminal" href="/cli/authentication">
+    Full authentication command reference
+  </Card>
+</CardGroup>
diff --git a/learn/data-and-search.mdx b/learn/data-and-search.mdx
new file mode 100644
index 0000000..c5cbe1b
--- /dev/null
+++ b/learn/data-and-search.mdx
@@ -0,0 +1,8 @@
+---
+title: "Coming Soon"
+description: "This lesson is under development"
+---
+
+<Note>
+This lesson is currently being developed. Check back soon!
+</Note>
diff --git a/learn/dynamic-jobs.mdx b/learn/dynamic-jobs.mdx
new file mode 100644
index 0000000..c5cbe1b
--- /dev/null
+++ b/learn/dynamic-jobs.mdx
@@ -0,0 +1,8 @@
+---
+title: "Coming Soon"
+description: "This lesson is under development"
+---
+
+<Note>
+This lesson is currently being developed. Check back soon!
+</Note>
diff --git a/learn/ecommerce.mdx b/learn/ecommerce.mdx
new file mode 100644
index 0000000..c5cbe1b
--- /dev/null
+++ b/learn/ecommerce.mdx
@@ -0,0 +1,8 @@
+---
+title: "Coming Soon"
+description: "This lesson is under development"
+---
+
+<Note>
+This lesson is currently being developed. Check back soon!
+</Note>
diff --git a/learn/full-project.mdx b/learn/full-project.mdx
new file mode 100644
index 0000000..c5cbe1b
--- /dev/null
+++ b/learn/full-project.mdx
@@ -0,0 +1,8 @@
+---
+title: "Coming Soon"
+description: "This lesson is under development"
+---
+
+<Note>
+This lesson is currently being developed. Check back soon!
+</Note>
diff --git a/learn/integrations.mdx b/learn/integrations.mdx
new file mode 100644
index 0000000..c5cbe1b
--- /dev/null
+++ b/learn/integrations.mdx
@@ -0,0 +1,8 @@
+---
+title: "Coming Soon"
+description: "This lesson is under development"
+---
+
+<Note>
+This lesson is currently being developed. Check back soon!
+</Note>
diff --git a/learn/mcp-servers.mdx b/learn/mcp-servers.mdx
new file mode 100644
index 0000000..c5cbe1b
--- /dev/null
+++ b/learn/mcp-servers.mdx
@@ -0,0 +1,8 @@
+---
+title: "Coming Soon"
+description: "This lesson is under development"
+---
+
+<Note>
+This lesson is currently being developed. Check back soon!
+</Note>
diff --git a/learn/multi-channel.mdx b/learn/multi-channel.mdx
new file mode 100644
index 0000000..c5cbe1b
--- /dev/null
+++ b/learn/multi-channel.mdx
@@ -0,0 +1,8 @@
+---
+title: "Coming Soon"
+description: "This lesson is under development"
+---
+
+<Note>
+This lesson is currently being developed. Check back soon!
+</Note>
diff --git a/learn/persona-design.mdx b/learn/persona-design.mdx
new file mode 100644
index 0000000..c5cbe1b
--- /dev/null
+++ b/learn/persona-design.mdx
@@ -0,0 +1,8 @@
+---
+title: "Coming Soon"
+description: "This lesson is under development"
+---
+
+<Note>
+This lesson is currently being developed. Check back soon!
+</Note>
diff --git a/learn/processors.mdx b/learn/processors.mdx
new file mode 100644
index 0000000..c5cbe1b
--- /dev/null
+++ b/learn/processors.mdx
@@ -0,0 +1,8 @@
+---
+title: "Coming Soon"
+description: "This lesson is under development"
+---
+
+<Note>
+This lesson is currently being developed. Check back soon!
+</Note>
diff --git a/learn/production-ops.mdx b/learn/production-ops.mdx
new file mode 100644
index 0000000..c5cbe1b
--- /dev/null
+++ b/learn/production-ops.mdx
@@ -0,0 +1,8 @@
+---
+title: "Coming Soon"
+description: "This lesson is under development"
+---
+
+<Note>
+This lesson is currently being developed. Check back soon!
+</Note>
diff --git a/learn/push-and-deploy.mdx b/learn/push-and-deploy.mdx
new file mode 100644
index 0000000..c5cbe1b
--- /dev/null
+++ b/learn/push-and-deploy.mdx
@@ -0,0 +1,8 @@
+---
+title: "Coming Soon"
+description: "This lesson is under development"
+---
+
+<Note>
+This lesson is currently being developed. Check back soon!
+</Note>
diff --git a/learn/scheduled-jobs.mdx b/learn/scheduled-jobs.mdx
new file mode 100644
index 0000000..c5cbe1b
--- /dev/null
+++ b/learn/scheduled-jobs.mdx
@@ -0,0 +1,8 @@
+---
+title: "Coming Soon"
+description: "This lesson is under development"
+---
+
+<Note>
+This lesson is currently being developed. Check back soon!
+</Note>
diff --git a/learn/skills-and-tools.mdx b/learn/skills-and-tools.mdx
new file mode 100644
index 0000000..c5cbe1b
--- /dev/null
+++ b/learn/skills-and-tools.mdx
@@ -0,0 +1,8 @@
+---
+title: "Coming Soon"
+description: "This lesson is under development"
+---
+
+<Note>
+This lesson is currently being developed. Check back soon!
+</Note>
diff --git a/learn/testing.mdx b/learn/testing.mdx
new file mode 100644
index 0000000..c5cbe1b
--- /dev/null
+++ b/learn/testing.mdx
@@ -0,0 +1,8 @@
+---
+title: "Coming Soon"
+description: "This lesson is under development"
+---
+
+<Note>
+This lesson is currently being developed. Check back soon!
+</Note>
diff --git a/learn/user-state.mdx b/learn/user-state.mdx
new file mode 100644
index 0000000..c5cbe1b
--- /dev/null
+++ b/learn/user-state.mdx
@@ -0,0 +1,8 @@
+---
+title: "Coming Soon"
+description: "This lesson is under development"
+---
+
+<Note>
+This lesson is currently being developed. Check back soon!
+</Note>
diff --git a/learn/webhooks.mdx b/learn/webhooks.mdx
new file mode 100644
index 0000000..c5cbe1b
--- /dev/null
+++ b/learn/webhooks.mdx
@@ -0,0 +1,8 @@
+---
+title: "Coming Soon"
+description: "This lesson is under development"
+---
+
+<Note>
+This lesson is currently being developed. Check back soon!
+</Note>
diff --git a/learn/your-first-agent.mdx b/learn/your-first-agent.mdx
new file mode 100644
index 0000000..c5cbe1b
--- /dev/null
+++ b/learn/your-first-agent.mdx
@@ -0,0 +1,8 @@
+---
+title: "Coming Soon"
+description: "This lesson is under development"
+---
+
+<Note>
+This lesson is currently being developed. Check back soon!
+</Note>