DiogoKaster · Oct 7, 2026
@@ -66,6 +66,7 @@ A typical flow:
 | `depth` | `quick` · `standard` · `deep` | `standard` |
 | `handsOn` | `off` · `light` (rarely, 1–5 lines) · `moderate` | `light` |
 | `diagrams` | `true` · `false` | `true` |
+| `diagramStyle` | `text` (works in any terminal) · `mermaid` (for viewers that render it) | `text` |
 
 Your profile lives in `~/.tacit/profile.md` — plain markdown you can read and edit. It never leaves your machine through Tacit.
 

@@ -14,6 +14,7 @@ version: 1
 depth: standard        # quick | standard | deep
 handsOn: light         # off | light | moderate
 diagrams: true
+diagramStyle: text     # text | mermaid
 languages: [typescript, sql]
 updated: 2026-10-06
 ---

@@ -37,9 +37,52 @@ Concepts not present in the catalog can still be taught — explain them from yo
 
 ## Diagrams
 
-- Use **Mermaid** fenced blocks (`flowchart`, `sequenceDiagram`, `erDiagram`, `classDiagram`). They render on GitHub, VS Code and most markdown viewers.
-- When the environment clearly cannot render Mermaid (plain terminal), also include a compact ASCII version.
-- Diagram what the learner needs right now: the overall flow at the start, a sequence diagram for a request crossing layers, an ER diagram for schema changes. Never more than one diagram per message.
+Most learners read Tacit in a terminal, where Mermaid shows up as raw source. So the default is a **text diagram**, which reads the same everywhere.
+
+Read `diagramStyle` from the learner profile (default `text`):
+
+- `text`: draw the diagram with characters inside a ` ```text ` fenced block.
+- `mermaid`: use Mermaid fenced blocks (`flowchart`, `sequenceDiagram`, `erDiagram`). Only for learners who read Tacit somewhere that renders it (IDE chat panels, markdown viewers). The size rules below still apply.
+
+### Fit the screen
+
+- **At most 60 columns wide** and about **8 boxes**. Terminals are often split or narrow, and wide lines get cut or wrapped.
+- **Flow top to bottom**, not left to right: vertical scrolls, horizontal gets cut.
+- **Short labels**: names and verbs only. Details go in the text below the diagram.
+- Box-drawing characters and arrows (`─ │ ┌ ┐ └ ┘ ├ ▶ ▼`) are fine. Avoid emoji and other wide characters — they break alignment.
+
+### Split big diagrams
+
+If the picture doesn't fit those limits, split it:
+
+1. An **overview** with the main parts as single boxes (e.g. `API`, `Services`, `Database`).
+2. One **detail diagram per part**, shown when the walkthrough reaches that part — not all at once.
+
+For a sequence with more than 4 participants, use a numbered list of steps instead of lanes.
+
+### Example
+
+```text
+Before
+  Internet (no login)
+    │ GET /api/backup-database
+    ▼
+  routes/api.php
+    │
+    ▼
+  BackupController::backup
+    ├─▶ mysqldump
+    └─▶ git push
+
+Now
+  GET /api/backup-database ──▶ 404 Not Found
+                                  ▲
+  BackupRouteRemovedTest ─────────┘ checks
+```
+
+### What to draw
+
+Diagram what the learner needs right now: the overall flow at the start, the path of a request crossing layers, the tables and their relationships for schema changes. Never more than one diagram per message.
 
 ## Hands-on
 

@@ -32,7 +32,7 @@ At most **one** think-first question per slice — pick the concept closest to `
 
 ## 1. Load the learner profile
 
-Read `~/.tacit/profile.md`. If it doesn't exist, use the defaults (`depth: standard`, `handsOn: light`, `diagrams: true`, every concept `unseen`) and continue — don't ask for setup now.
+Read `~/.tacit/profile.md`. If it doesn't exist, use the defaults (`depth: standard`, `handsOn: light`, `diagrams: true`, `diagramStyle: text`, every concept `unseen`) and continue — don't ask for setup now.
 
 ## 2. Understand the task
 

@@ -41,7 +41,7 @@ Explain and ask for each, with the default in bold:
 
 - **Depth**: `quick` (only essentials) / **`standard`** / `deep` (trade-offs and alternatives)
 - **Hands-on**: `off` / **`light`** (rarely, 1–5 lines) / `moderate` (small exercises every few files)
-- **Diagrams**: **on** / off
+- **Diagrams**: **on** / off. If on, ask where they read the agent's replies: a **terminal** (`diagramStyle: text`, default) or somewhere that renders Mermaid, like an IDE chat panel (`diagramStyle: mermaid`).
 
 ## 5. Save and confirm
 

@@ -17,7 +17,7 @@ Before starting, read these files (paths relative to this skill's directory):
 
 ## 1. Load the learner profile
 
-Read `~/.tacit/profile.md`. If it doesn't exist, use the defaults (`depth: standard`, `handsOn: light`, `diagrams: true`, every concept `unseen`) and continue — don't ask for setup now.
+Read `~/.tacit/profile.md`. If it doesn't exist, use the defaults (`depth: standard`, `handsOn: light`, `diagrams: true`, `diagramStyle: text`, every concept `unseen`) and continue — don't ask for setup now.
 
 ## 2. Resolve the scope
 
@@ -37,7 +37,7 @@ Ignore lockfiles, generated files, build output, binary assets and pure formatti
 In the first message:
 
 1. One or two sentences on **what was built**, in plain language.
-2. A diagram of how the files connect (if `diagrams` is on) — usually a `flowchart` from entry point to storage.
+2. A diagram of how the files connect (if `diagrams` is on), from entry point to storage, following the diagram rules in teaching-method.md. If the change is big, show only the overview here and the details as each part comes up.
 3. The **reading order**: list the files in dependency order, from foundations to the edges (schema/models → domain/services → API/handlers → UI → tests). Tests can be visited right after the code they cover.
 4. Tell them how it works: one file at a time, short questions, and they can say "skip" anytime.
 
@@ -50,7 +50,7 @@ For each file:
 1. **Purpose** — what this file is responsible for, in one or two sentences.
 2. **Key code** — point to the important parts with short excerpts (≤15 lines) and line references. Don't paste whole files.
 3. **Concepts** — identify the concepts the file uses. Match them to the catalog (`../../concepts/INDEX.md`) and read the concept file for any concept you're going to teach. Treat each one according to its profile status (see teaching-method.md). Language-specific idioms count as concepts too.
-4. **Connection** — how this file relates to the previous ones and what uses it next. A sequence diagram helps when a request crosses several layers.
+4. **Connection** — how this file relates to the previous ones and what uses it next. A diagram of the request path helps when it crosses several layers.
 5. **Question** — when a concept is new or shaky, end with **one** question (see question-types.md), plus the skip option. Otherwise, end by asking if they want to continue.
 
 Then **stop and wait for the learner's reply.** Never answer your own question, and never cover the next file in the same message.