Merge pull request #37 from itsflaid/codex/add-onboarding-command

Improve onboarding guide generation

Author: itsflaid

PRD.md

@@ -618,7 +618,7 @@ DevMap automatically detects the language used by the user.
 
 - `devmap ask`
 - `devmap explain` *(future)*
-- `devmap onboard` *(future)*
+- `devmap onboarding`
 - `devmap docs` *(future)*
 
 ### CLI Metadata
@@ -1072,7 +1072,7 @@ Future CI should test:
 
 | Command | Phase | Priority |
 |---|---|---|
-| `devmap onboard` | Phase 3 | High |
+| `devmap onboarding` | MVP 0.1.0 candidate | High |
 | `devmap docs` | Phase 3 | Medium |
 | `devmap flow` | Phase 4 | Medium |
 | `devmap trace` | Phase 4 | Medium |
@@ -1083,7 +1083,7 @@ Future CI should test:
 
 ---
 
-### `devmap onboard` *(Phase 3 — High Priority)*
+### `devmap onboarding` *(MVP 0.1.0 Candidate)*
 
 Purpose: developer productivity accelerator.
 
@@ -1120,7 +1120,8 @@ docs/
 ```
 
 `devmap docs` generates documentation artifacts.  
-`devmap onboard` generates a learning/productivity guide.
+`devmap onboarding` generates a learning/productivity guide from the current
+snapshot. `devmap onboard` remains a shorthand alias.
 
 These are related but not the same.
 

README.md

@@ -105,6 +105,7 @@ snapshot.json
 | `DEVMAP.md`             | DevMap instructions  |
 | `AGENTS.md`             | AI agent entry point |
 | `.devmap/snapshot.json` | Core project context |
+| `ONBOARDING.md`         | Optional onboarding guide |
 
 The snapshot is the primary output of DevMap.
 
@@ -136,13 +137,19 @@ devmap analyze
 # Verify your setup
 devmap doctor
 
+# Generate a reading guide from the snapshot
+devmap onboarding
+devmap onboarding --write
+devmap onboarding --write --language id
+
 # Ask questions about your codebase
 devmap ask "explain the main architecture"
 devmap ask "where is the auth logic?"
 devmap ask "what external services does this use?"
 
 # Machine-readable output for AI agents and scripts
 devmap ask "where is the auth logic?" --json
+devmap onboarding --json
 ```
 
 ---
@@ -295,19 +302,19 @@ Node.js 18+
 * [x] `devmap init`
 * [x] `devmap analyze`
 * [x] `devmap ask`
+* [x] `devmap onboarding`
 * [x] `devmap doctor`
 
 ### Next
 
-* [ ] `devmap onboard`
 * [ ] `devmap features`
+* [ ] `devmap flow`
 * [ ] OpenAI provider
 * [ ] Gemini provider
 
 ### Later
 
 * [ ] `devmap explain`
-* [ ] `devmap flow`
 * [ ] `devmap docs`
 * [ ] Local AI mode
 * [ ] VS Code Extension

docs/commands.md

@@ -6,15 +6,17 @@
 
 ## Overview
 
-DevMap MVP provides four core project commands and one configuration command:
+DevMap MVP provides five core project commands and one configuration command:
 
 * `devmap init`
-* `devmap analyze`
-* `devmap ask`
+* `devmap analyze`
+* `devmap ask`
+* `devmap onboarding`
 * `devmap doctor`
 * `devmap config model`
 
-No additional product commands should be added until the MVP is shipped.
+Additional product commands should wait until the MVP is shipped unless the PRD
+explicitly promotes them into the `0.1.0` scope.
 
 Future commands are documented in:
 
@@ -395,9 +397,9 @@ Running quick analysis first...
 
 Then continue answering the question.
 
-### Stale Snapshot Behavior
-
-If project files changed after last analyze:
+### Stale Snapshot Behavior
+
+If project files changed after last analyze:
 
 ```txt
 Project changed since last analyze.
@@ -407,12 +409,78 @@ Use existing snapshot or re-analyze first?
 [1] Use existing snapshot
 [2] Re-analyze now
 ```
-
----
-
+
+---
+
+## `devmap onboarding`
+
+Generate a project onboarding guide from the current snapshot.
+
+Alias: `devmap onboard`
+
+### Purpose
+
+`devmap onboarding` turns `.devmap/snapshot.json` into a practical reading
+guide for humans and AI agents. It should help answer:
+
+> Where should I start reading this project?
+
+### Usage
+
+```bash
+devmap onboarding
+devmap onboarding --write
+devmap onboarding --write --language id
+devmap onboarding --json
+```
+
+### Responsibilities
+
+* Read `.devmap/snapshot.json`
+* Use `project`, `onboarding.recommendedPath`, `features`, `flows`,
+  `criticalFiles`, and `changeImpact`
+* Include a concise project narrative from snapshot facts, with a trimmed
+  architecture note when useful
+* Surface entry points, external services, and critical files before the
+  reading path
+* Print a readable terminal guide by default
+* Show a follow-up hint explaining that `--write` creates `ONBOARDING.md`
+* Write `ONBOARDING.md` when `--write` is passed
+* Ask for Indonesian or English when writing from an interactive terminal and
+  no language is provided
+* Use `--language en` or `--language id` to skip the prompt
+* Emit one structured JSON document when `--json` is passed
+* Warn when the snapshot is stale
+
+### Output Sections
+
+1. What This Project Does
+2. Mental Model
+3. Main Concepts
+4. Important Areas to Understand
+5. Key Flows
+6. Where to Start
+
+### Rules
+
+* Do not invent files that are not present in the snapshot
+* Prefer snapshot-derived paths over generic advice
+* Avoid placeholder wording such as `not inferred yet`; omit unavailable fields
+* Explain what each important file is responsible for and why it should be read
+* Avoid raw metadata dumps such as scores, import counts, and exported symbol
+  lists in human onboarding output
+* Keep the guide useful without requiring an AI call
+* Treat `devmap flow` and full docs generation as future commands
+* Include snapshot freshness and agent navigation policy in JSON output
+* Keep `--json` non-interactive; never prompt in machine-readable mode
+* Default generated onboarding language is English; use `--language id` for
+  Bahasa Indonesia
+
+---
+
 ## `devmap doctor`
-
-Run diagnostics for DevMap setup.
+
+Run diagnostics for DevMap setup.
 
 ### Purpose
 
@@ -542,6 +610,7 @@ devmap init --json
 devmap analyze --json
 devmap analyze --deep --json
 devmap ask "where is authentication handled?" --json
+devmap onboarding --json
 devmap doctor --json
 devmap config model auto --json
 ```
@@ -559,8 +628,9 @@ Contract:
   DevMap JSON document
 
 `analyze --json` returns the project snapshot. `ask --json` returns the answer,
-selected files, model, and token usage. `doctor --json` returns diagnostics and
-issues as structured fields.
+selected files, model, and token usage. `onboarding --json` returns guide
+metadata and Markdown. `doctor --json` returns diagnostics and issues as
+structured fields.
 
 ---
 
@@ -575,8 +645,7 @@ They are not part of the current MVP command scope.
 | `devmap features` | Detect implemented project features         |
 | `devmap explain`  | Explain folders, modules, and architecture  |
 | `devmap flow`     | Explain system flows as narrative steps     |
-| `devmap docs`     | Generate project documentation              |
-| `devmap onboard`  | Generate onboarding guide                   |
+| `devmap docs`     | Generate project documentation              |
 | `devmap deadcode` | Detect unused files, exports, and functions |
 | `devmap report`   | Generate project health report              |
 | `devmap watch`    | Auto-update snapshot on file changes        |

docs/design.md

@@ -172,9 +172,10 @@ Start with:
 
 Popular commands:
 
-  devmap analyze        scan current project
-  devmap ask "..."      ask your codebase
-```
+  devmap analyze        scan current project
+  devmap ask "..."      ask your codebase
+  devmap onboarding     generate reading guide
+```
 
 ---
 

docs/development-testing.md

@@ -7,6 +7,7 @@ Packaged-command verification should include machine-readable output:
 ```bash
 devmap analyze --json
 devmap ask "where is the main entry point?" --json
+devmap onboarding --json
 devmap doctor --json
 ```
 
@@ -29,6 +30,8 @@ With a live Groq key, run:
 devmap analyze --fresh
 devmap ask "explain the main architecture"
 devmap ask "explain the main architecture" --json
+devmap onboarding
+devmap onboarding --write
 ```
 
 Human output should appear progressively without raw Markdown markers. JSON

docs/for-me-personal/PROGRESS.md

@@ -1,6 +1,27 @@
 # Progress DevMap
 
-Terakhir diperbarui: 2026-06-18
+Terakhir diperbarui: 2026-06-19
+
+## Update 2026-06-19
+
+### Onboarding Command
+
+- `devmap onboarding` ditambahkan sebagai kandidat MVP 0.1.0, dengan alias
+  `devmap onboard`.
+- Command membaca `.devmap/snapshot.json` dan menghasilkan guide berbasis
+  snapshot tanpa membutuhkan AI call.
+- Output human berisi Project Overview, Recommended Reading Path, Feature Map,
+  Important Flows, Change Impact Notes, dan Agent Workflow.
+- `devmap onboarding --write` menulis `ONBOARDING.md`.
+- `devmap onboarding --json` menghasilkan satu dokumen JSON untuk agent,
+  editor, atau script.
+- README, PRD, command docs, roadmap, design docs, dan CLI README diperbarui
+  supaya onboarding tidak lagi tercatat sebagai future-only command.
+- Renderer onboarding direfaktor menjadi guide pemahaman untuk developer dan
+  AI agent: pembuka menjelaskan tujuan project, mental model, konsep utama,
+  area penting untuk dibaca, flow penting, dan rekomendasi mulai membaca.
+- Default bahasa onboarding tetap English, sementara `--language id` dan prompt
+  interaktif `--write` tetap dapat menghasilkan Bahasa Indonesia.
 
 ## Update 2026-06-18
 

docs/for-me-personal/TEST.md

@@ -15,6 +15,51 @@ Ada beberapa versi DevMap yang dapat diuji:
 | npm link | CLI global sementara | Menguji command `devmap` dari folder mana pun |
 | CI/runtime | OS dan versi Node berbeda | Verifikasi lintas platform sebelum release |
 
+## Onboarding Command
+
+Focused automated test:
+
+```powershell
+pnpm --filter devmap exec tsx --test test/onboarding-command.test.ts test/json-output.test.ts
+```
+
+Manual source-mode check dari root DevMap:
+
+```powershell
+$root = (Get-Location).Path
+pnpm dev:cli analyze "$root"
+pnpm dev:cli onboarding "$root"
+pnpm dev:cli onboarding "$root" --json
+pnpm dev:cli onboarding "$root" --write
+pnpm dev:cli onboarding "$root" --write --language id
+```
+
+Catatan: `pnpm dev:cli` memakai `pnpm --filter devmap`, sehingga command
+source-mode berjalan dari `packages/cli`. Untuk mengetes root workspace DevMap,
+selalu kirim path target eksplisit seperti contoh di atas.
+
+Expected result:
+
+- `devmap onboarding` membaca `.devmap/snapshot.json` yang sudah ada.
+- Jika snapshot belum ada atau stale, jalankan `pnpm dev:cli analyze` dulu.
+- Jika snapshot stale, human output memberi warning dan JSON berisi
+  `snapshot.stale: true`.
+- JSON output menyertakan `agentInstructions` agar agent mengikuti policy
+  snapshot-first.
+- Human output berfokus sebagai guide pemahaman, bukan file index: What This
+  Project Does, Mental Model, Main Concepts, Important Areas to Understand, Key
+  Flows, dan Where to Start.
+- Setiap file penting dalam reading area menyertakan `Purpose` dan
+  `Why read this`, bukan score/import count/export list mentah.
+- Entry point kosong di feature/flow tidak boleh ditampilkan sebagai
+  `not inferred yet`; field tersebut cukup dihilangkan.
+- `--json` menghasilkan satu dokumen JSON tanpa ANSI atau dekorasi terminal.
+- `--write` membuat atau memperbarui `ONBOARDING.md` di root project target.
+- Di terminal interaktif, `--write` menanyakan bahasa onboarding jika
+  `--language` belum diberikan. Default bahasa tetap English.
+- `--language en` dan `--language id` melewati prompt, cocok untuk automation
+  dan agent.
+
 ## Context Builder Ranking
 
 Jalankan focused test ranking dan evaluation:

docs/roadmap.md

@@ -41,17 +41,19 @@ adding AI on top. If the foundation is wrong, AI output will be wrong too.
 - Stale snapshot detection + user prompt
 - All error scenarios handled (no raw stack traces)
 
-**Deliverable:** `devmap analyze` with AI interpretation.
-`devmap ask` with context-aware answers.
+**Deliverable:** `devmap analyze` with AI interpretation,
+`devmap ask` with context-aware answers, and `devmap onboarding` for a
+snapshot-based reading guide when the output is stable enough for `0.1.0`.
 
 ---
 
 ## Phase 3 — Documentation Generation
 **Goal:** DevMap generates useful project documentation automatically.
 
 **Tasks:**
-- `devmap docs` — generate structured markdown docs folder
-- `devmap onboard` — generate onboarding guide with reading order
+- `devmap docs` — generate structured markdown docs folder
+- Expand `devmap onboarding` beyond the MVP guide when richer snapshot fields
+  are available
 
 **Deliverable:**
 ```
@@ -118,6 +120,6 @@ Not planned. Not scheduled. Revisit when Phase 5 ships.
 | 1.0.0 | 2 | Stable `devmap analyze` + `devmap ask` release |
 | 1.1.0 | 2 | Performance improvements, cache optimization |
 | 1.2.0 | 2 | Express support solidified |
-| 2.0.0 | 3 | `devmap docs` + `devmap onboard` |
+| 2.0.0 | 3 | `devmap docs` + expanded onboarding |
 | 3.0.0 | 4 | `devmap deadcode` + `devmap flow` + `devmap report` |
 | 4.0.0 | 5 | OpenAI + Gemini support |