magellan-cli 0.1.2

Deterministic presentation engine for AI-generated technical walkthroughs
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123

magellan - Render structured technical walkthroughs into terminal, markdown, or HTML output.

Magellan is a deterministic presentation engine for AI-generated walkthroughs.
It does not inspect a repository by itself and it does not call an LLM.
An agent or engineer gathers evidence, writes a structured JSON payload, and
then uses Magellan to validate and render that payload.

Usage:
  magellan schema
  magellan prompt --agent-type <codex|claude> [--source <session|diff|branch|pr>] [--goal <walkthrough|followup|handoff>] [options]
  magellan example --preset <walkthrough|timeline|before-after>
  magellan validate --input <payload.json|->
  magellan render --input <payload.json|-> --format <terminal|markdown|html> [--out <path>] [--open]
  magellan guide

Commands:
  schema    Print the JSON Schema for Magellan's input payload.
  prompt    Print an agent-oriented prompt template for producing a Magellan walkthrough.
  example   Print a starter payload that agents can edit before rendering.
  validate  Validate a JSON payload without rendering it.
  render    Render a JSON payload into terminal, markdown, or HTML output.
  guide     Print this help text.

Global options:
  -h, --help     Print this help text.
  -V, --version  Print version.

Core rule:
  Explain behavior, flow, architecture, timeline, or verification.
  Do not narrate file churn.

Normal workflow:
  1. Decide what evidence you are using.
     - session messages, tool actions, and timestamps
     - current diff or commit range
     - branch compared to trunk
     - pull request description, comments, and diff
  2. Learn the payload contract.
     - run: `magellan schema`
     - optional starter payload: `magellan example --preset walkthrough`
  3. Write a JSON payload with:
     - `title`
     - `summary`
     - `sections`
     - optional `verification`
  4. Validate the payload.
     - run: `magellan validate --input /tmp/magellan.json`
  5. Render the final artifact.
     - terminal: `magellan render --input /tmp/magellan.json --format terminal`
     - markdown: `magellan render --input /tmp/magellan.json --format markdown`
     - html: `magellan render --input /tmp/magellan.json --format html --open`

Content rules:
  - Keep the summary to 1-2 short paragraphs.
  - Keep sections to 3-6 focused chunks.
  - Keep section text short.
  - In HTML, each section becomes a page in book view.
  - In book view, diagrams can be clicked to enlarge.
  - Use diagrams only when they make the technical explanation easier to follow.
  - Ground the content in real evidence from code, diffs, tests, and session history.

Diagram picking:
  sequence         Request or actor-by-actor interaction flow
  flow             Branching logic or state movement
  component_graph  Steady-state relationships between modules or layers
  timeline         Ordered work, debugging steps, or event progression
  before_after     User-visible behavior change

Prompt workflow:
  Use `magellan prompt` when you want Magellan to teach the agent how to build
  the payload.

  Useful prompt knobs:
  - `--source`: where the evidence comes from
  - `--goal`: broad walkthrough, follow-up answer, or engineer handoff
  - `--question`: a narrow question to answer directly
  - `--scope`: keep the artifact inside a subsystem, route, or flow
  - `--focus`: emphasize behavior, architecture, timeline, verification, or decisions

  Examples:
  - `magellan prompt --agent-type codex`
  - `magellan prompt --agent-type codex --source session --goal walkthrough`
  - `magellan prompt --agent-type codex --source diff --goal followup --question "why did this flow change?"`
  - `magellan prompt --agent-type claude --source branch --goal handoff --scope backend --scope tests --focus verification --focus decisions`

Render targets:
  terminal  Best for in-chat or terminal output with ASCII diagrams
  markdown  Best for chat messages, docs, or PR comments with Mermaid blocks
  html      Best for a paced visual walkthrough

HTML behavior:
  HTML reports are self-contained and open in book view by default.

  Book view:
  - starts with the summary
  - shows one technical slice per page
  - supports page navigation
  - lets the user click diagrams to enlarge them

  Overview view:
  - shows the full walkthrough as one stacked report

Reference files:
  Use these checked-in payloads when you want realistic examples:
  - `examples/session-walkthrough.json`
  - `examples/branch-handoff-timeline.json`
  - `examples/followup-validation-question.json`

Fast paths:
  Learn the contract:
  - `magellan schema`

  Start from a built-in preset:
  - `magellan example --preset timeline`

  Study a realistic HTML report:
  - `magellan render --input examples/session-walkthrough.json --format html --open`

  Answer a focused follow-up:
  - `magellan prompt --agent-type codex --source diff --goal followup --question "why did this API flow change?"`

  Prepare a handoff:
  - `magellan prompt --agent-type claude --source branch --goal handoff --scope backend --scope tests`