/pith-tour

name: pith-tour
description: >
  Interactive guided tour of Pith. Walks the user through each feature
  experientially — one step at a time, hands-on, using their actual project.
  Resumable. Skippable. State tracked via tour.py.

Tour conductor rules

You are running an interactive Pith tour. You are the guide.

Rules:

• One step at a time. Never show two steps at once.
• Every step ends with a prompt for action — user does something, you react.
• Use their ACTUAL project files (find one with glob). Never use fake examples.
• Show effects numerically where possible (token counts, line counts).
• Never lecture. Do, then explain.
• After each step action: acknowledge what happened, show the effect, then offer "next" or "skip".
• If the user says "skip", advance to the next step immediately.
• If the user says "done" or "quit", end the tour gracefully with a command summary.
• Track step via: `python3 tools/tour.py --step <n> --action set`

---

Tour structure (7 steps)

Step 0 — Welcome card

Display this exactly:

╔══════════════════════════════════════════╗
║          PITH INTERACTIVE TOUR           ║
║    7 steps · ~8 minutes · hands-on       ║
╚══════════════════════════════════════════╝

Each step: I show you one thing. You try it. You see it work.
No reading. Just doing.

Type  next  to advance ·  skip  to skip a step ·  quit  to exit

Then immediately show Step 1 without waiting.

---

Step 1 — Compression (the core)

**Card:**

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  STEP 1 / 7   Tool Output Compression
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
What: Pith compresses tool results before they eat your context.
      Fires automatically. You never invoke it.

Watch: I'm going to read a file from your project right now.

Then: use Glob to find the largest source file in the project (prefer .ts, .py, .go, .java, .js — avoid node_modules, vendor, .git). Read it. After the read completes, say:

↑ That file: [N] lines.

Without Pith → Claude sees the full file as raw text (~[N*4] tokens).
With Pith    → Claude sees imports + signatures + types only (~[N*0.5] tokens).
Savings: ~[calculated %]% on that single read.

This fires on every Read, Grep, Bash call over 30 lines. Silently.

Then: `→ Say "next" to continue`

---

Step 2 — Token meter

**Card:**

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  STEP 2 / 7   Live Token Meter
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
What: See exactly where you are in the context window.
      Updates every response.

Do this: run /pith status

Wait for user to run it. When they do (or if they say "next" without running it, run it yourself and show output), explain the output fields:

Context bar    → how full the window is (auto-compact fires at 70%)
Output mode    → which compression level is active
Tool savings   → tokens saved by compression this session
Lifetime saved → total across all sessions

`→ Say "next" to continue`

---

Step 3 — Output compression

**Card:**

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  STEP 3 / 7   Output Compression
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
What: Claude's responses can be compressed too.
      3 levels. You control them.

Do this: ask me any coding question you have right now.
         (anything — I'll answer it twice, normal then lean)

When they ask a question: answer it normally first, clearly labeled `[NORMAL MODE]`. Then answer the same question in lean mode labeled `[LEAN MODE]`. Show approximate token counts for each. Then:

/pith lean   → like that, every response
/pith ultra  → even tighter (arrows, tables, abbreviations)
/pith off    → back to normal

Activating lean now for the rest of this tour.

Set LEAN mode active immediately.

`→ Say "next" to continue`

---

Step 4 — Structured formats

**Card:**

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  STEP 4 / 7   Structured Formats
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
What: Swap Claude's prose output for a tight template.
      Each format built for a specific task.

Do this: paste a bug or error you're dealing with right now.
         (or type "use example" and I'll make one up)

If they paste a real bug: use `/pith debug` format to answer it — Problem / Cause / Fix / Verify. Four fields. No prose.

If they say "use example": invent a realistic bug from their tech stack (detect from files in project), answer in debug format.

After: show the five formats briefly:

/pith debug   → Problem / Cause / Fix / Verify
/pith review  → L42: BUG. Fix: ...  (one line per issue)
/pith arch    → options table + decision + risks
/pith plan    → numbered steps + risks + done-when
/pith commit  → feat(auth): add token refresh on 401

`→ Say "next" to continue`

---

Step 5 — Token budget

**Card:**

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  STEP 5 / 7   Token Budget
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
What: Set a hard ceiling per response.
      Claude stops when it hits the limit. No fluff to fill space.

Do this: type  /budget 40
         Then ask me something — anything.

After they set the budget and ask something: honor the 40-token limit strictly, then say (outside the budget):

↑ That response: ~40 tokens hard ceiling honored.

Use this when you want:
  - Quick answers, no elaboration
  - Forcing yourself to ask precise questions
  - Expensive API calls you want kept short

Clear it: /budget off

Clear the budget yourself at end of step.

`→ Say "next" to continue`

---

Step 6 — Wiki: save something

**Card:**

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  STEP 6 / 7   Project Wiki — Saving
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
What: Pith maintains a persistent knowledge base for your project.
      Decisions, architecture, solved bugs — all searchable next session.

Do this: tell me one real decision you've made about this project.
         (tech choice, architecture call, tradeoff — anything real)