Tutorial — Learn HQ by Doing

Interactive, modular lessons teaching HQ principles through hands-on exercises against the user's real HQ. Each topic follows a 5-phase flow: Concept, Show, Exercise, Verify, Takeaway. Content sources include Build Your Own AGI (where available) and the core/knowledge/public/getting-started/ docs — the book is a supporting reference, not a prerequisite.

Ordering rationale: Lead with principles and daily workflow — most users won't run /run-project orchestration until they've lived in HQ. Ralph-loop orchestration (Topic 8) and worker authoring (Topic 9) come last, where users have enough context to appreciate them.

Input: $ARGUMENTS — optional topic slug. If empty, show topic menu.

Step 0: Parse Input

If $ARGUMENTS is non-empty, match against topic slugs:

Input	Topic
cloud, team, collaboration, hq-sync, hq-share, hq-secrets, hq-deploy, hq-bug	0. Cloud & Team Collaboration
principles, ralph-principles, mindset	1. Ralph Principles
hq, workflow, daily, folder, folders	2. Working with HQ
knowledge	3. Knowledge Architecture
session-hygiene, hygiene, sessions	4. Session Hygiene
context-management, context, tokens	5. Context Management
projects, prd, prds	6. Projects
scaling, parallel, multi-session	7. Scaling
ralph-loop, ralph, loop, run-project	8. The Ralph Loop (Orchestration)
workers, worker	9. Workers

If matched: skip to Step 2 with that topic. If no match: show error + topic menu (Step 1). If empty: proceed to Step 1.

Step 1: Topic Menu

Maturity Detection

Silently assess HQ state:

1. Check core/workers/registry.yaml — count company-specific workers (type: company)
2. Check for any prd.json files in companies/*/projects/ or personal/projects/
3. Count companies in companies/manifest.yaml
4. Cloud / team detection — silently run:

   grep -l 'cloud' companies/*/manifest.yaml 2>/dev/null | head -1
   grep -iE 'cloud_backed|cloud_uid|hq[-_]?pro|team' companies/manifest.yaml 2>/dev/null | head -3
   

   Either signal hit → flag as CLOUD.

Classify:

• FRESH: 0 custom workers AND 0 projects
• ACTIVE: has workers OR projects
• ADVANCED: 3+ companies with core/workers/projects
• CLOUD (orthogonal flag): cloud-backed / HQ Pro / team context detected. Sits alongside FRESH/ACTIVE/ADVANCED — when present, Topic 0 leads the menu and is the default recommendation regardless of maturity.

Present Menu

Menu structure adapts to the CLOUD flag:

• CLOUD detected → render the "Cloud & Team Collaboration" block FIRST, above Foundations. Topic 0 is the default recommendation.
• CLOUD not detected → omit the Cloud block entirely. Foundations leads.

HQ Tutorial
───────────
Learn HQ principles from "Build Your Own AGI" — interactive lessons
with hands-on exercises using your actual HQ.

  Cloud & Team Collaboration                       [shown only if CLOUD detected]
  0. Cloud & Team           — hq-sync, hq-share, hq-secrets, hq-deploy, hq-bug

  Foundations
  1. Ralph Principles      — Plan mode, fresh context, back pressure (mindset)
  2. Working with HQ       — Daily workflow: /startwork → work → /handoff

  Daily Practice
  3. Knowledge             — Hot vs cold channels, qmd search, gardens
  4. Session Hygiene       — /checkpoint, /handoff, thread files
  5. Context Management    — Token optimization, Context Diet, advisories
  6. Projects              — PRDs, /idea → /plan, acceptance criteria
  7. Scaling               — Parallel sessions, company isolation

  Advanced
  8. The Ralph Loop        — /run-project orchestration (principles in action)
  9. Workers               — /newworker, worker.yaml, /learn training

  Recommended for you: {see below}

  Full book: {your-book-site}

Recommendation logic:

• CLOUD (any maturity) → "0. Cloud & Team — learn how your HQ talks to the cloud, your team, and shared secrets before going deeper"
• FRESH (no cloud) → "1. Ralph Principles — start with the mindset before the mechanics"
• ACTIVE (no cloud) → "4. Session Hygiene — the #1 thing that separates productive users from frustrated ones"
• ADVANCED (no cloud) → "8. The Ralph Loop — you're ready for orchestrated execution via /run-project"

Wait for user selection via AskUserQuestion. Route to Step 2 with chosen topic.

Step 2: Run Lesson

Execute the 5-phase lesson flow for the selected topic. Each phase is described below.

Phase 1: Concept (synthesize, don't paste)

1. Attempt to read book chapter. Check if the book exists at personal/knowledge/curriculum/book/handbook.md; on not-yet-migrated installations, fall back to the legacy repos/private/knowledge-curriculum/book/handbook.md (reading it is fine — note that hq reindex migrates it). If found, read ONLY the line range for this topic's chapter (see Topic Registry below). If neither exists, use fallback sources.
2. Read the HQ reference file(s) listed in the topic's hq_refs field.
3. Synthesize a 200-300 word explanation of the core concept in your own words. Do NOT paste paragraphs from the book.
4. Surface the key quote defined for this topic — attribute it to the book.
5. Link to the book: "Full chapter: Ch {N} in Build Your Own AGI — {your-book-site}"

Phase 2: Show (inspect user's HQ)

Run the read-only inspection commands defined in the topic's show field. Annotate what you find with how it connects to the concept just explained.

Two paths:

• Has content: Inspect real data (workers, projects, threads, settings) and annotate.
• No content: Explain what it would look like when populated. Use shared/bundled HQ content as examples.

Phase 3: Exercise (hands-on)

Present the exercise defined in the topic's exercise field.

Exercise tiers:

• Tier 1 (AI executes, read-only): qmd searches, file reads, git log, ls, wc. Safe to run directly.
• Tier 2 (User executes, AI verifies): Commands like /run, /checkpoint. Describe what to do, wait for the user to try, then verify.
• Tier 3 (Suggested for later, NOT executed): /newworker, /plan, /run-project, /handoff. Mention as next steps only.

Phase 4: Verify

For Tier 1 exercises: present what the exercise revealed and ask the user a comprehension question. For Tier 2 exercises: check for expected side effects (new files, updated state) or ask "What did you see?"

Phase 5: Takeaway

1. State the one principle from this topic (defined in takeaway field).
2. Reference existing docs: "Quick reference: core/knowledge/public/getting-started/cheatsheet.md"
3. Suggest next topic: "Next: try /tutorial {next_topic} or pick another from /tutorial"
4. Book link: "Deeper dive: Ch {N} in Build Your Own AGI — {your-book-site}"

---

Topic Registry

Topic 0: cloud — Cloud & Team Collaboration (CLOUD-gated)

• Chapter: N/A — HQ product, not Ralph philosophy

• HQ refs: .claude/skills/{hq-sync,hq-share,hq-secrets,deploy,hq-bug}/SKILL.md, companies/manifest.yaml

• Voice: plain-English "if you want X, do Y." Lead each command with the need, then explain what happens, when to use it, and the one gotcha worth knowing. No jargon-first, no policy citations up front.

• Opening framing: "When you're working solo, HQ lives on your laptop. When you're working with a team — or just want your laptop and the cloud to agree — these 5 commands are the bridge. Each one answers a specific question:"

• Show: present the 5 commands as a needs-based menu. Use this framing:

  • Want your laptop's HQ to match the cloud (or push local changes up)? → /hq-sync (or just tell Claude "sync HQ") Reconciles every cloud-backed company in both directions. Runs the same engine as the HQ Desktop App "Sync" button. Use it at the start of a session if you switched machines, or at the end if you want a teammate to see what you just did. If there are conflicts (you and the cloud changed the same file), HQ surfaces them — /resolve-conflicts walks you through each one.

  • Want to give a teammate access to a file or folder? → /hq-share <path> Generates a one-time link, opens a picker in your browser, and lets you grant any teammates you want (one or many at once). The link is live for 15 minutes and only works once — that's by design, so a leaked link can't be reused. After you've granted access, the teammates have it permanently; the link is just the handoff.

  • Want to upload API keys / passwords so you and your team can use them without copy-pasting? → /hq-secrets Stores credentials in the cloud per company. Once stored, any teammate with access can use them in their sessions without ever seeing the raw value — Claude fetches them at runtime and never prints them in chat. Best for: Shopify tokens, Stripe keys, database URLs, anything you'd otherwise paste into a .env file. If a credential needs a human to log in (OAuth, 2FA), HQ mints a link to send instead.

  • Want to publish something (a doc, preview site, report) so others can see it? → /deploy Ships whatever you just made — a generated report, a brief, a static page — to the hq-deploy host and returns a shareable URL. Optional password protection if it's sensitive. Use this when chat-pasting a long doc would be awkward, or when you want a single link that teammates can bookmark.

  • Hit a bug or want a feature in HQ itself? → /hq-bug Files a report directly to the HQ team. Auto-attaches your session context (which command was running, what failed, what directory you were in) so you don't have to write a repro. Use it freely — friction here is the difference between a fixed bug and a forgotten one.

• Exercise (Tier 1):

  1. Read companies/manifest.yaml → name the user's cloud-backed companies (the ones with cloud_uid: or similar markers)
  2. Ask the user: "Of the 5, which scenario actually fits something you want to do today? Pick one and I'll walk you through it." Map their answer to the command and explain the first step

• Verify: user can answer "which command for X?" for each of the 5 scenarios in their own words — not by reciting the command name, but by knowing which problem it solves

• Takeaway: "5 commands, 5 jobs. /hq-sync keeps you and the cloud in agreement. /hq-share hands access to a teammate. /hq-secrets stores credentials safely. /deploy turns work into a link. /hq-bug closes the loop with HQ itself. Together they're the team-collab layer — the rest of HQ is what you do inside that layer."

• Next: principles (FRESH) or hq (ACTIVE)

Topic 1: principles — Ralph Principles (NEW)

• Chapter: 3 — "The Loop That Changed Everything" (mindset/philosophy portions only — not orchestrator mechanics)
• Book lines: 243-336
• Fallback: core/knowledge/public/getting-started/quick-start-guide.md (Core Loop section), core/knowledge/public/getting-started/learning-path.md (Module 1-2)
• HQ refs: core/knowledge/public/getting-started/quick-start-guide.md
• Key quote: "AI in ask mode is not AGI. AI in plan mode can be."
• Focus discipline: This topic teaches the mindset — plan mode, fresh context, back pressure — NOT /run-project mechanics. Do not reference /run-project, sub-agents, or file locking here. Those live in Topic 8 (ralph-loop). If the user asks about orchestration, say: "That's Topic 8 — come back after you internalize the three principles."
• Show:
  • Read a recent thread file from workspace/threads/ (most recent .json). Annotate where the three principles show up: where did the session start with plan mode? Where was context refreshed? Where was a task verified before advancing?
  • If no threads exist, read .claude/settings.json and point to the planModeByDefault or thinking-mode settings as the "plan mode" principle made concrete
• Exercise (Tier 1):
  1. Read one past thread file from workspace/threads/ (or the bundled sample if fresh)
  2. Ask the user: "Ralph has three principles. Looking at this session, can you name them and point to one moment in the thread that embodies each?" (Answer: plan mode, fresh context per task, back pressure/verification)
• Verify: User identifies the three principles AND can point to at least two of them in the thread. If they miss one, explain it with a concrete example.
• Takeaway: "Plan before act. Fresh context per task. Verify before advancing. The principles are the operating system — everything else (workers, projects, /run-project) is just how HQ makes them repeatable."
• Next topic: hq

Topic 2: hq — Working with HQ (NEW)

• Chapter: 4 — "Building Your HQ — The Operating System Nobody Gave You"
• Book lines: 337-448
• Fallback: core/knowledge/public/getting-started/quick-start-guide.md (Daily Workflow section), core/knowledge/public/getting-started/cheatsheet.md
• HQ refs: core/knowledge/public/getting-started/quick-start-guide.md, core/knowledge/public/getting-started/cheatsheet.md
• Key quote: "HQ is a filesystem with opinions." (If no exact match in Ch 4, synthesize an equivalent from the chapter's opening framing and attribute as paraphrase.)
• Focus discipline: Daily workflow arc (/startwork → work → /handoff) + folder orientation. Do NOT teach /run-project here (Topic 8) or worker authoring (Topic 9). The goal: a user should know where to look and which command to run next on day one.
• Show:
  • List top-level HQ dirs: ls -1 $HOME/Documents/HQ/ (filter hidden). For each of .claude/, companies/, core/knowledge/, core/workers/, workspace/, repos/ — explain in one line what it holds
  • Read core/knowledge/public/getting-started/cheatsheet.md — show the daily cadence table/section
  • Show the typical command sequence from the book: /startwork → (work happens) → /checkpoint (mid-session) → /handoff (end)
• Exercise (Tier 1):
  1. From companies/manifest.yaml, pick a company the user works in. Locate one file in each of: companies/{co}/settings/, companies/{co}/knowledge/, companies/{co}/workers/. Show the user what each holds
  2. Ask: "If you opened HQ tomorrow morning and wanted to resume yesterday's work, what's the first command you'd run and what file would it read?" (Answer: /startwork reads workspace/threads/handoff.json)
• Verify: User can name /startwork and locate handoff.json. If they don't know the handoff file, read the 7-line handoff.json to them as a demo of how little state resumes a session.
• Takeaway: "HQ is a filesystem with opinions. Every dir has a job. The daily arc is /startwork → work → /handoff. Learn the arc before learning the advanced commands."
• Next topic: knowledge

Topic 3: knowledge

• Chapter: 6 — "The Knowledge Problem"
• Book lines: 545-636
• Fallback: core/knowledge/public/getting-started/quick-start-guide.md (Knowledge section), core/knowledge/public/getting-started/learning-path.md (Module 5)
• HQ refs: core/knowledge/public/getting-started/quick-start-guide.md
• Key quote: "HQ without knowledge is a library with empty shelves."
• Show:
  • List core/knowledge/public/ directories — show what knowledge bases exist
  • Count total knowledge files: ls core/knowledge/public/ and any companies/*/knowledge/
  • Show the two supported knowledge storage forms: a plain real directory or a real directory with embedded git. Explain that symlinked knowledge repositories are invalid because sync cannot materialize their contents
• Exercise (Tier 1):
  1. Pick a keyword relevant to the user's work (ask them for one via AskUserQuestion)
  2. Run qmd search "{keyword}" --json -n 5 (BM25 keyword search)
  3. Run qmd vsearch "{keyword}" --json -n 5 (semantic/vector search)
  4. Compare results — explain: keyword search finds exact terms; semantic search finds related concepts
• Verify: User sees different results between search types and can articulate when to use which.
• Takeaway: "Cold channels store, hot channels decide. Your knowledge base is the one asset nobody can replicate."
• Next topic: session-hygiene

Topic 4: session-hygiene

• Chapter: 8 — "Session Hygiene — Why Your AI Gets Dumber Over Time"
• Book lines: 739-828
• Fallback: core/knowledge/public/getting-started/cheatsheet.md, core/knowledge/public/getting-started/learning-path.md (Module 8)
• HQ refs: core/knowledge/public/getting-started/cheatsheet.md
• Key quote: "Close early, close often. /handoff is your end-of-day save button."
• Show:
  • Check workspace/threads/handoff.json — if exists, read and explain its structure (what gets preserved between sessions)
  • List recent thread files in workspace/threads/ — show the checkpoint/handoff history
  • Show the auto-checkpoint configuration in CLAUDE.md (the PostToolUse hook table)
• Exercise (Tier 2):
  1. Tell the user: "Run /checkpoint right now to see session saving in action."
  2. Wait for user to run it
  3. After they confirm, read the most recent thread file in workspace/threads/ and walk through what it captured
• Verify: A new thread file exists in workspace/threads/ with a recent timestamp, or ask the user what they observed.
• Takeaway: "Fresh sessions beat long sessions. /handoff is 30 seconds. The next session starts smarter because of it."
• Next topic: context-management

Topic 5: context-management

• Chapter: 4 + 8 — "Building Your HQ" + "Session Hygiene"
• Book lines: 337-448 (Ch 4), 739-828 (Ch 8) — read Ch 4 only, reference Ch 8 from session-hygiene
• Fallback: core/knowledge/public/getting-started/learning-path.md (Module 8)
• HQ refs: .claude/CLAUDE.md (Context Diet and Token Optimization sections only — do NOT read the full file)
• Key quote: "Your AI goes from genius to mass-hallucinator the further into the context window you get."
• Show:
  • Read the Context Diet section of CLAUDE.md (the bullet list of rules)
  • Show the Token Optimization table (env vars and their purpose)
  • Show the context-threshold checkpoint system (50% checkpoint + pre-compact backup)
• Exercise (Tier 1):
  1. Read the Context Diet rules in CLAUDE.md — count the "do NOT" rules
  2. Run wc -l .claude/CLAUDE.md — show the instruction file size as an example of keeping context tight
  3. Examine: "Every file you Read costs tokens. What does the Context Diet section tell you NOT to read at session start?" (Answer: INDEX.md, agents files, company knowledge — unless the task requires it)
• Verify: User can name 2-3 context diet rules from memory.
• Takeaway: "Context is a finite resource. The discipline is knowing what NOT to load. Load what the task needs, nothing more."
• Next topic: projects

Topic 6: projects

• Chapter: 7 — "How to Run a Project at Machine Speed"
• Book lines: 637-738
• Fallback: core/knowledge/public/getting-started/quick-start-guide.md (PRDs section), core/knowledge/public/getting-started/learning-path.md (Module 6)
• HQ refs: core/knowledge/public/getting-started/quick-start-guide.md
• Key quote: "Don't over-specify. State outcomes, not methods. Let the system discover the best approach."
• Show:
  • Search for existing prd.json files: qmd search "prd.json userStories" --json -n 5
  • If any exist: read one and walk through the structure — name, stories, acceptance criteria, passes field, files array
  • If none: explain the structure using the PRD schema from the book, emphasizing acceptance criteria as the "teeth"
• Exercise (Tier 1 + Tier 3 suggestion):
  1. If a prd.json exists: read it and ask "How many stories are in this project? How many have passed verification?" Show how passes: true/false creates back pressure
  2. If none: explain the /idea → /brainstorm → /plan → /run-project pipeline. Suggest: "Try /idea to capture something small on your board."
• Verify: User understands that acceptance criteria define "done" for autonomous agents — without them, the loop has no back pressure.
• Takeaway: "A PRD is a to-do list with teeth. Acceptance criteria are how autonomous agents know when to stop."
• Next topic: scaling

Topic 7: scaling

• Chapter: 9 — "Scaling to Many — Running 6-8 Agents in Parallel"
• Book lines: 829-936
• Fallback: core/knowledge/public/getting-started/learning-path.md (Modules 9-10)
• HQ refs: companies/manifest.yaml
• Key quote: "This is not multitasking. This is multiplying."
• Show:
  • Read companies/manifest.yaml — count companies, show the isolation structure (each company → repos, workers, knowledge, settings)
  • Check workspace/orchestrator/active-runs.json — show parallel session tracking if any runs exist
  • Explain company isolation: separate sessions, credential routing via manifest, policy scoping
• Exercise (Tier 1):
  1. Read companies/manifest.yaml and count: companies, total repos across all companies, total workers
  2. Read the Company Isolation hard rules from CLAUDE.md (the "NEVER" list)
  3. Ask: "If you were running sessions for two different companies simultaneously, what prevents you from accidentally using Company A's credentials in Company B's session?" (Answer: manifest-based credential routing, company-scoped policies, cross-company hooks)
• Verify: User can explain at least one isolation mechanism (manifest routing, policies, or hooks).
• Takeaway: "Parallelism is what separates operators from power users. Company isolation is the guardrail that makes it safe."
• Next topic: ralph-loop

Topic 8: ralph-loop — The Ralph Loop (Orchestration) (rescoped)