@orbweva/academy 0.2.0

package/SECURITY.md

@@ -0,0 +1,34 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+Email **security@orbweva.com** with subject `[academy] <short summary>`. Please **do not** open a public GitHub issue.
+
+We aim to acknowledge within 72 hours.
+
+## What this installer does (threat model)
+
+`@orbweva/academy` performs a narrow set of operations on your machine:
+
+1. **Shells out to `git`** to shallow-clone public GitHub repos under `https://github.com/ORBWEVA/*` into a temp directory.
+2. **Reads files from the cloned temp dirs** and copies `skills/<name>/` folders into either `~/.claude/skills/` (global) or `./.claude/skills/` (project-local).
+3. **Prints suggested shell commands** for CLI tool installs (`brew`, `winget`, `scoop`, `npm -g`) and MCP server setup (`claude mcp add …`). **These are not executed automatically** — you must copy/paste them.
+4. **Removes the temp directory** after copying.
+
+It does not: write to `~/.claude.json`, edit shell dotfiles, run arbitrary commands from any repo, reach any server besides GitHub, or transmit telemetry.
+
+## Trust boundaries
+
+- **Source of skills** — only repos listed in `manifest.json` under the `ORBWEVA/*` namespace. A malicious PR attempting to add a third-party repo must pass review.
+- **Runtime dependencies** — none (beyond Node 18+ and system `git`). Zero `node_modules`.
+- **`npx` trust** — running `npx @orbweva/academy` executes arbitrary npm-published code. Audit the published version by running `npm view @orbweva/academy` before installing, or `git clone` this repo and run `node bin/install.js` directly.
+
+## Disclosure timeline
+
+We follow coordinated disclosure:
+
+1. Reporter emails security@orbweva.com.
+2. We triage within 72 hours.
+3. Fix developed privately; release candidate shared with reporter.
+4. Patch released + CVE filed if applicable.
+5. Public advisory 7–30 days after patch release, depending on severity.

package/bin/install.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { run } from '../src/cli.js';
+
+run(process.argv.slice(2)).catch((err) => {
+  console.error(`\n\x1b[31m✗\x1b[0m ${err.message}`);
+  if (process.env.ORBWEVA_DEBUG) console.error(err.stack);
+  process.exit(1);
+});

package/docs/CLI-TOOLS.md

@@ -0,0 +1,232 @@
+# CLI Tools Reference
+
+The `@orbweva/academy` installer prints platform-specific CLI install commands at the end of every run. This doc is the expanded version with every gotcha.
+
+**The installer never executes these for you.** Copy and run them yourself.
+
+---
+
+## macOS
+
+```bash
+# Node version manager + GitHub CLI + Supabase CLI
+brew install fnm gh supabase/tap/supabase
+
+# Switch to LTS Node
+fnm install --lts
+fnm default lts-latest
+
+# Package managers
+npm install -g pnpm vercel
+
+# Sign in to GitHub
+gh auth login
+```
+
+That's the whole thing. Total time: ~5 min on a reasonable connection.
+
+---
+
+## Windows
+
+Windows has three gotchas that will each cost you 30 minutes if you don't know them. Read these before running anything:
+
+### Gotcha 1: You need TWO PowerShell windows at the same time
+
+| Window | How to open | What it's for |
+|---|---|---|
+| **Admin PowerShell** | Start → type `powershell` → right-click **Windows PowerShell** → **Run as administrator** | `winget install` commands *only* |
+| **Regular PowerShell** | Start → type `powershell` → left-click | `scoop`, `npm install -g`, `gh auth login`, `claude`, day-to-day work |
+
+**Why:** `winget` needs admin. `scoop` *refuses* to install as admin (it'll print `Running the installer as administrator is disabled by default`).
+
+Keep both open — you'll use admin for ~2 minutes, then close it.
+
+### Gotcha 2: New CLIs don't work until PATH refreshes
+
+After any `winget install` or `scoop install`, the current window has a stale PATH. If you run `gh --version` right after installing gh and see `gh : The term 'gh' is not recognized`, the install worked — PATH just hasn't refreshed.
+
+**Fix (one-liner):**
+
+```powershell
+$env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path","User")
+```
+
+(Or just close and reopen the window.)
+
+You'll use this a few times. Keep it handy.
+
+### Gotcha 3: `EBADENGINE` warnings on `npm install -g` are harmless
+
+If you have Node v25 (or any odd-numbered / non-LTS version), `pnpm` and `vercel` will print:
+
+```
+npm WARN EBADENGINE Unsupported engine
+```
+
+They still install and work fine — pnpm/vercel haven't declared support for experimental Node versions. **Ignore the warning.** Step 2 below switches you to LTS Node anyway, which makes them disappear.
+
+---
+
+### Step 1 — In Admin PowerShell, install winget tools
+
+```powershell
+winget install Schniz.fnm
+winget install GitHub.cli
+```
+
+Refresh PATH in the admin window:
+
+```powershell
+$env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path","User")
+fnm --version
+gh --version
+```
+
+Both should print version numbers. **You can close Admin PowerShell now** — everything else runs in regular PowerShell.
+
+### Step 2 — In regular PowerShell, install Node LTS
+
+```powershell
+fnm install --lts
+fnm default lts-latest
+node --version
+npm --version
+```
+
+`node --version` should show **v22.x** (the current LTS).
+
+> If you see a higher number like v25, that's a stray Node install from nodejs.org. It'll still work for the ORBWEVA curriculum, but every `npm install` will print `EBADENGINE` warnings. Clean up: Windows Settings → "Apps & features" → search "Node" → uninstall, then reopen PowerShell.
+
+### Step 3 — Install Scoop (for Supabase CLI)
+
+Scoop **must** be installed in regular (non-admin) PowerShell.
+
+```powershell
+Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
+```
+
+Press **Y** and Enter if prompted.
+
+```powershell
+irm get.scoop.sh | iex
+```
+
+Wait ~20 seconds until you see `Scoop was installed successfully!`. Refresh PATH:
+
+```powershell
+$env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path","User")
+scoop --version
+```
+
+### Step 4 — Install the remaining CLIs
+
+```powershell
+# Supabase CLI (via scoop)
+scoop install supabase
+
+# pnpm — fast package manager, cross-platform via npm
+npm install -g pnpm
+
+# Vercel CLI — deploy and manage from terminal
+npm install -g vercel
+```
+
+Verify:
+
+```powershell
+supabase --version
+pnpm --version
+vercel --version
+```
+
+### Step 5 — Log in to GitHub
+
+```powershell
+gh auth login
+```
+
+You'll be asked four questions. Answers in order:
+
+1. **"Where do you use GitHub?"** → **GitHub.com** (Enter)
+2. **"Preferred protocol for Git operations?"** → **HTTPS** (Enter)
+   *Why HTTPS, not SSH: no key management, works through any firewall, `gh` handles credentials via Windows Credential Manager.*
+3. **"Authenticate Git with your GitHub credentials?"** → **Y** (Enter)
+   *This wires `git push` / `git pull` to reuse your gh token. Skip this and you'll be typing usernames and passwords forever.*
+4. **"How would you like to authenticate GitHub CLI?"** → **Login with a web browser** (Enter)
+
+PowerShell then prints something like:
+
+```
+! First copy your one-time code: ABCD-1234
+Press Enter to open https://github.com/login/device in your browser...
+```
+
+> **⚠ The 8-character code is in your PowerShell window, NOT the browser.** First-timers always miss this. Copy it (or write it down), *then* press Enter. The browser opens a page with 8 boxes — paste the code, click **Continue**, sign in to GitHub if asked, click **Authorize GitHub CLI**. The browser says "Congratulations", and PowerShell shows `✓ Authentication complete.`
+
+Verify:
+
+```powershell
+gh auth status
+```
+
+### Step 6 — Sanity check
+
+```powershell
+fnm --version
+node --version
+npm --version
+pnpm --version
+vercel --version
+gh --version
+supabase --version
+```
+
+All seven should return version numbers.
+
+---
+
+## Linux
+
+```bash
+# Node version manager
+curl -fsSL https://fnm.vercel.app/install | bash
+fnm install --lts
+fnm default lts-latest
+
+# GitHub CLI — varies by distro
+sudo apt install gh   # Debian/Ubuntu
+# or: brew install gh (if you use Homebrew on Linux)
+
+# Package managers
+npm install -g pnpm vercel
+
+# Supabase CLI — see https://supabase.com/docs/guides/local-development/cli/getting-started
+
+# Sign in to GitHub
+gh auth login
+```
+
+---
+
+## Phase 2 tools (install later, not now)
+
+```bash
+# Stripe CLI — for testing webhooks locally (Week 8 of the Accelerator)
+# macOS
+brew install stripe/stripe-cli/stripe
+# Windows
+scoop install stripe
+# Linux — see https://docs.stripe.com/stripe-cli#install
+
+# ngrok — expose localhost for webhook testing (Week 6)
+# macOS
+brew install ngrok
+# Windows
+winget install Ngrok.Ngrok
+
+# Playwright — browser testing (Week 6). Runs in any project folder
+npm install -D @playwright/test
+```
+
+For the full list of CLIs, MCPs, and IDE extensions at each phase, see the **[ORBWEVA Accelerator Skills Reference](https://orbweva.com/en/accelerator/skills)**.

package/docs/MCP-SERVERS.md

@@ -0,0 +1,116 @@
+# MCP Servers
+
+After the installer prints the CLI tools section, it prints a list of MCP (Model Context Protocol) servers to wire into Claude Code. This doc covers what each one does and how to configure it.
+
+**The installer prints `claude mcp add ...` commands — it doesn't run them.** Copy and run them yourself, after setting any required environment variables.
+
+## What MCP is
+
+MCP lets Claude Code talk directly to external services (Supabase, GitHub, Playwright, your filesystem) without leaving the session. Instead of Claude telling you to "open a new terminal and run X", Claude just calls the tool.
+
+Full docs: https://docs.claude.com/en/docs/claude-code/mcp
+
+## Recommended servers
+
+### `supabase`
+
+Required for: `accelerator`, `mentoring`, `founder`, any track that builds web apps.
+
+**What it does:** Query your Supabase databases, run migrations, deploy edge functions, read logs.
+
+**Setup:**
+
+```bash
+# 1. Get your Supabase access token from https://supabase.com/dashboard/account/tokens
+export SUPABASE_ACCESS_TOKEN=sbp_...
+
+# 2. Add to Claude Code
+claude mcp add supabase npx -y @supabase/mcp-server-supabase
+```
+
+On Windows PowerShell, use `$env:SUPABASE_ACCESS_TOKEN = "sbp_..."` instead of `export`.
+
+### `context7`
+
+Required for all tracks — heavily used by skills for fetching current library docs.
+
+**What it does:** Fetches up-to-date documentation for libraries, frameworks, SDKs (React, Next.js, Prisma, etc.) so Claude doesn't rely on training-data-era knowledge.
+
+**Setup:**
+
+```bash
+claude mcp add context7 npx -y @upstash/context7-mcp
+```
+
+No API key required.
+
+### `playwright`
+
+Optional. Required if you're doing web app testing (Week 6 of Accelerator).
+
+**What it does:** Browser automation — take screenshots, run E2E tests, inspect rendered pages.
+
+**Setup:**
+
+```bash
+claude mcp add playwright npx -y @playwright/mcp
+```
+
+No API key required.
+
+### `memory`
+
+Optional. Useful for long-running projects with persistent knowledge graphs.
+
+**What it does:** Stores entities + relations across sessions. Used by some skills for retaining project context.
+
+**Setup:**
+
+```bash
+claude mcp add memory npx -y @modelcontextprotocol/server-memory
+```
+
+No API key required.
+
+## Per-track recommendations
+
+| Track | Recommended MCPs |
+|---|---|
+| `accelerator` | supabase, context7, playwright, memory |
+| `course` | context7 (others optional) |
+| `mentoring` | supabase, context7, memory |
+| `founder` | context7 (supabase if client builds on it) |
+| `full` | all four |
+
+## Adding more MCPs
+
+MCP servers not listed here that are useful at various points:
+
+- **GitHub MCP** — repo/PR/issue operations (`@modelcontextprotocol/server-github`)
+- **Stripe MCP** — billing integration work (`@stripe/mcp`)
+- **Figma MCP** — design-to-code workflows (`figma-developer-mcp`)
+- **n8n MCP** — workflow automation integration
+
+See the [ORBWEVA Accelerator Skills Reference](https://orbweva.com/en/accelerator/skills) for the full list of MCPs used in the curriculum.
+
+## Verifying your MCP setup
+
+In Claude Code:
+
+```
+/mcp
+```
+
+Lists all registered MCP servers and their connection status.
+
+If a server shows as disconnected, check:
+
+1. The command in `claude mcp list` matches the docs (no typos).
+2. Required env vars are set in the shell where you started Claude Code.
+3. The npm package exists — `npm view <package-name>` should succeed.
+
+## Removing an MCP server
+
+```bash
+claude mcp remove <name>
+```

package/docs/PACKS.md

@@ -0,0 +1,136 @@
+# Specialization Packs
+
+Packs are **stackable add-ons** to tracks. They layer vertical-specific skills on top of any base track so a student building a marketing agency gets the same founder foundation as a student building a web-video studio — plus their specialization.
+
+## How packs compose
+
+```
+final skill set = track.required
+                ∪ track.optional (the ones you approve)
+                ∪ pack1.required
+                ∪ pack1.optional (approved)
+                ∪ pack2 ...
+```
+
+Shared repos are **deduped automatically**. If both the track and a pack reference `gtm-skills`, it's installed once.
+
+You can stack any number of packs:
+
+```bash
+npx @orbweva/academy@latest --track accelerator --pack marketing --pack web-video
+```
+
+## Available packs
+
+> **Status note**: The three packs below are defined in `manifest.json` with `status: "planned"`. Their GitHub repos haven't been published yet, so the installer warns and skips them gracefully. They'll work automatically once the repos go live.
+
+### `loka`
+
+**For:** Founders building a business on the Loka living-textbook + LoLA avatar platform. Example user: Kyubin Park (Kora Lingo).
+
+**Required repo:** `ORBWEVA/loka-pack` → skill `loka-integration`
+
+Content covers Loka API integration, LoLA avatar configuration, living-textbook content management, Hooks/webhook patterns, persistent learner profiles.
+
+```bash
+npx @orbweva/academy@latest --track accelerator --pack loka
+```
+
+---
+
+### `marketing`
+
+**For:** Solo operators or small-team marketing agencies. Content marketing, SEO, brand work, client delivery.
+
+**Required repo:** `ORBWEVA/marketing-pack` → skill `marketing-agency`
+**Optional (inherited):** `solo`, `agents`
+
+```bash
+npx @orbweva/academy@latest --track accelerator --pack marketing
+```
+
+---
+
+### `web-video`
+
+**For:** Design studios delivering web design + video editing as a service.
+
+**Required repo:** `ORBWEVA/web-video-pack` → skills `web-design`, `video-editing`
+**Optional (inherited):** `solo`
+
+```bash
+npx @orbweva/academy@latest --track accelerator --pack web-video
+```
+
+---
+
+## Adding a new pack
+
+The pack system is designed so new verticals can be added without touching code. Everything lives in `manifest.json`.
+
+### Step 1 — Add the skill repo
+
+If the pack has its own repo:
+
+```json
+{
+  "skillRepos": {
+    ...
+    "my-pack": {
+      "repo": "ORBWEVA/my-pack",
+      "skills": ["my-skill-name"]
+    }
+  }
+}
+```
+
+If the repo doesn't exist yet, add `"status": "planned"` so the installer skips it gracefully:
+
+```json
+"my-pack": {
+  "repo": "ORBWEVA/my-pack",
+  "skills": ["my-skill-name"],
+  "status": "planned"
+}
+```
+
+### Step 2 — Define the pack
+
+```json
+{
+  "packs": {
+    ...
+    "my-pack-key": {
+      "label": "My Pack",
+      "tagline": "One-line description for the menu",
+      "required": ["my-pack"],
+      "optional": ["solo-skills"]
+    }
+  }
+}
+```
+
+`required` and `optional` reference **repo keys** (from `skillRepos`), not skill names.
+
+### Step 3 — Verify
+
+```bash
+node bin/install.js --help
+```
+
+Your new pack should appear in the help listing.
+
+```bash
+node bin/install.js --track accelerator --pack my-pack-key --dry-run --yes --global
+```
+
+### Step 4 — Update the CHANGELOG
+
+Add an entry under `[Unreleased]`.
+
+## When to use a pack vs. a new track
+
+- **New track** — the audience uses a *different base program*. Founder base for Leanne's clients is a track because the engagement model is different from the Accelerator.
+- **New pack** — the audience uses the *same base program* but needs vertical-specific skills on top. A marketing founder running through the Accelerator needs the Accelerator skills *and* marketing-specific ones.
+
+In most cases: **pack**. Tracks change rarely.

package/docs/TRACKS.md

@@ -0,0 +1,141 @@
+# Tracks
+
+A **track** is a base program — one per install. Pick the one that matches how you're engaging with ORBWEVA.
+
+## Track summary
+
+| Track | For | Skills | Typical duration |
+|---|---|---|---|
+| [`accelerator`](#accelerator) | 12-week cohort — zero-to-one founders | 15 | 12 weeks |
+| [`course`](#course) | Self-paced founder fundamentals | 9 | ~8 weeks |
+| [`mentoring`](#mentoring) | 1:1 operator support for existing businesses | 13 | Ongoing |
+| [`founder`](#founder) | Partner-delivered lean base | 10 | Varies |
+| [`full`](#full) | Everything — no tradeoffs | 15 | — |
+
+---
+
+## Accelerator
+
+**Who:** Founders going zero-to-one with direct mentor access from Ryan Ahamer.
+**Format:** 12-week cohort, daily meetings, fortnightly reviews, graduation criteria at week 12.
+**Cost:** $2,500–$5,000 one-time (no equity).
+
+### Skills (15)
+
+**Required (7 repos, 9 skills):**
+- `secure-setup` — git-ignore rules, credential hygiene
+- `core` — ORBWEVA CORE Method (/core:assess, /core:arc, /core:aer, /core:grow)
+- `resume` — `/resume` for session continuity
+- `discovery` — customer discovery, Mom Test interviews, JTBD
+- `design-thinking` — 5-stage design thinking exercises
+- `startup-metrics` — PMF, unit economics, churn, runway
+- `geo`, `gtm-launch`, `seo-toolkit` — all three from gtm-skills
+
+**Optional (4 repos, 6 skills):**
+- `pitch` — investor outreach, deck, financials
+- `hiring`, `legal-essentials`, `retention` — from founder-ops
+- `solo` — solopreneur toolkit
+- `agents` — AI agent design recipes
+
+### Command
+
+```bash
+npx @orbweva/academy@latest --track accelerator
+```
+
+### Related
+
+- [ORBWEVA Accelerator Curriculum](https://github.com/ORBWEVA/accelerator-template) — 12-week week-by-week program guide
+- [Graduation Criteria](https://github.com/ORBWEVA/accelerator-template/blob/main/docs/GRADUATION_CRITERIA.md)
+
+---
+
+## Course
+
+**Who:** Self-paced learners who want the foundational skills without the cohort commitment.
+**Format:** No cohort, no meetings. Ryan is unavailable for direct support; community-only.
+**Cost:** $497–$997 one-time.
+
+### Skills (9)
+
+**Required (5 repos, 5 skills):** `secure-setup`, `core`, `resume`, `discovery`, `design-thinking`
+
+**Optional (2 repos, 4 skills):** `startup-metrics`, `geo`, `gtm-launch`, `seo-toolkit`
+
+### Command
+
+```bash
+npx @orbweva/academy@latest --track course
+```
+
+---
+
+## Mentoring
+
+**Who:** Operators of existing businesses (not zero-to-one) who want 1:1 strategic support.
+**Format:** Weekly or biweekly 1:1s, quarterly CORE reviews.
+**Cost:** $1,500–$3,500 per month.
+
+### Skills (13)
+
+**Required (5 repos, 7 skills):**
+- `secure-setup`, `core`, `resume`
+- `startup-metrics`
+- `hiring`, `legal-essentials`, `retention` (all three from `founder-ops`)
+
+**Optional (4 repos, 6 skills):** `pitch`, `geo`, `gtm-launch`, `seo-toolkit`, `solo`, `agents`
+
+### Command
+
+```bash
+npx @orbweva/academy@latest --track mentoring
+```
+
+---
+
+## Founder
+
+**Who:** Clients of partners who resell an ORBWEVA-powered founder base (e.g. Leanne Knowles / Headswitch clients).
+**Format:** Delivered by the partner; ORBWEVA provides skills + occasional escalation.
+**Cost:** Set by the partner.
+
+### Skills (10)
+
+**Required (5 repos, 5 skills):** `secure-setup`, `core`, `resume`, `discovery`, `design-thinking`
+
+**Optional (3 repos, 5 skills):** `startup-metrics`, `pitch`, `geo`, `gtm-launch`, `seo-toolkit`
+
+Notably excludes `founder-ops` (hiring/legal/retention — partner handles those), `solo`, and `agents`. Leaner than Accelerator.
+
+### Command
+
+```bash
+npx @orbweva/academy@latest --track founder
+```
+
+### Who uses this track
+
+Partners who want a consistent ORBWEVA foundation across their client base without the 12-week cohort structure. Example: Headswitch running its own coaching methodology on top of the ORBWEVA CORE method.
+
+---
+
+## Full
+
+**Who:** ORBWEVA staff, contributors, power users, curious explorers.
+**Format:** Everything, no tradeoffs.
+
+### Skills (15)
+
+All 11 public ORBWEVA skill repos, all 15 skills.
+
+### Command
+
+```bash
+npx @orbweva/academy@latest --track full --yes --global
+```
+
+---
+
+## Adding a new track
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md). In short: add an entry under `tracks` in `manifest.json`. No code changes needed.