viepilot 2.4.0 → 2.12.0

package/CHANGELOG.md

@@ -7,6 +7,133 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.12.0] - 2026-04-13
+
+### Added (FEAT-018 — Phase 75)
+- **`vp-crystallize --brownfield`**: Brownfield Mode — bootstrap `.viepilot/` project context from an existing codebase without a brainstorm session
+  - 12-category codebase scanner: build manifests (11 platforms), framework detection (40+ dep patterns), architecture layer inference (18 directory patterns), database schema signals, API contract detection, infrastructure config, environment config shape, test coverage, code quality tools, documentation files, git history, file extension survey
+  - Structured Scan Report (YAML) with DETECTED / ASSUMED / MISSING gap classification
+  - MUST-DETECT gap tier: blocks artifact generation until user fills interactively
+  - Synthetic brainstorm stub (`docs/brainstorm/session-brownfield-import.md`) for `vp-audit` compatibility
+  - Safety rules: never reads `.env`; skips `node_modules/`, `.git/`, `target/`, `build/`, `dist/`, `__pycache__/`, `.venv/`, `vendor/`
+  - `vp-audit` updated to accept brownfield stub as valid brainstorm source (no false-positive errors)
+  - `TRACKER.md` annotated with `## Brownfield Import` block on first-time bootstrap
+
+## [2.11.0] - 2026-04-13
+
+### Added (ENH-045 — Phase 74)
+- **`lib/proposal-generator.cjs`**: `getDesignConfig(projectContext)` helper + `DESIGN_CONFIGS` map (3 styles: modern-tech, enterprise, creative) — auto-selects palette from sector/audience/tone context
+- **`scripts/gen-proposal-pptx.cjs`**: `PALETTES` map with 3 colour schemes + 3 rich slide layouts (timeline-gantt, team-card, investment-visual) + generates `project-proposal-{modern-tech,enterprise,creative}.pptx` variants
+- **`workflows/proposal.md`**: dynamic slide count (no hard cap) + `designConfig` field in manifest + content-aware split rules (technicalNarrative > 4 → 2 slides; team > 4 → 2 slides; phases > 4 → 2 timeline slides) + DESIGN SELECTION AI prompt block
+- 31 contract tests in `vp-enh045-dynamic-slides.test.js`
+
+## [2.10.1] - 2026-04-11
+
+### Changed (ENH-044 — Phase 73)
+- **`lib/screenshot-artifact.cjs`**: `warnMissingTool(tool, installCmd)` — standardized stderr `⚠` warning when visual tool absent but artifacts exist; exports alongside existing helpers
+- **`workflows/proposal.md` Step 4c**: mandatory enforcement — `visualSlides[]` MUST be non-empty when artifacts exist; puppeteer absent → `warnMissingTool('puppeteer', ...)` + `addPlaceholderVisual()` (no more silent skip)
+- **`workflows/proposal.md` Step 7**: mandatory enforcement — Mermaid + ui/arch sections MUST be added when diagrams/artifacts exist; mmdc absent → text fallback + `warnMissingTool('mmdc', ...)`; puppeteer absent → placeholder paragraph + `warnMissingTool('puppeteer', ...)`
+- `warnMissingTool()` called once per missing tool per generation run (not per-diagram)
+- 16 tests in `vp-enh044-visual-enforce.test.js`
+
+## [2.10.0] - 2026-04-11
+
+### Added (ENH-043 — Phase 72)
+- **`lib/screenshot-artifact.cjs`**: `isMmdcAvailable()` — boolean guard for `mmdc` CLI on PATH; `renderMermaidToPng(source, outPath)` — renders Mermaid source string → PNG via `mmdc` CLI; returns null when mmdc absent (no crash)
+- **`scripts/gen-proposal-docx.cjs`**: `imageRunFromPng(pngPath, widthEmu, heightEmu)` → `ImageRun` (docx package) for embedding PNG as inline image; requires `screenshot-artifact.cjs` + `proposal-generator.cjs`; runtime visual embedding comment block documenting three injection points: Mermaid diagrams (renderMermaidToPng → ImageRun), UI prototype screenshot (before Executive Summary), architecture screenshot (after Technical Approach)
+- **`workflows/proposal.md` Step 7**: Diagram Reference updated to render `mermaidSource` → PNG via `renderMermaidToPng()`; documents `screenshotArtifact` for ui-direction + architect injection; all paths use `cleanupScreenshot()`; graceful fallback when mmdc/puppeteer absent
+- 19 tests in `vp-enh043-docx-visuals.test.js`; contracts +2 (769/769 total)
+
+## [2.9.0] - 2026-04-11
+
+### Added (ENH-042 — Phase 71)
+- **`lib/proposal-generator.cjs`**: `detectVisualArtifacts(sessionDir)` — auto-scans `.viepilot/ui-direction/{latest-session}/` for ui-direction pages (`index.html`, `pages/*.html`) and 10 architect workspace page types (`architecture.html`, `erd.html`, `sequence-diagram.html`, etc.)
+- **`lib/screenshot-artifact.cjs`** (new): `screenshotArtifact(htmlPath)` via optional puppeteer (headless Chrome) — returns `null` gracefully when puppeteer not installed; `isPuppeteerAvailable()` boolean guard; `cleanupScreenshot()` temp-file cleanup
+- **`workflows/proposal.md` Step 4c `detect_visual_artifacts`**: AI maps slide topics to HTML artifact files, produces `visualSlides[]` array with `slideIndex`, `artifactType`, `htmlPath`, `label` fields
+- **`scripts/gen-proposal-pptx.cjs`**: `addPlaceholderVisual(slide, label)` — styled navy+accent placeholder shape for when screenshots are unavailable; runtime integration comment block documenting the `screenshotArtifact` → `addImage` → `cleanupScreenshot` pattern
+- Zero breaking change: all proposal generation works without puppeteer; visuals are additive
+
+## [2.8.0] - 2026-04-11
+
+### Added (ENH-041 — Phase 70)
+- **`workflows/proposal.md` Step 4b `generate_docx_content`**: dedicated AI pass for deep `.docx` content, independent of the slide manifest — richer prose, risk analysis, diagrams
+- **`docxContent` JSON schema**: `executiveSummary[]`, `problemStatement[]`, `solutionNarrative[]`, `technicalNarrative[]`, `riskRegister[]`, `glossary[]`, `diagrams[]` (with `mermaidSource`)
+- **Step 7 updated**: `.docx` generator consumes `docxContent` for narrative paragraphs; new Risk Register and Glossary sections fed from `docxContent`
+- **Step 8 updated**: `.md` companion embeds Mermaid fenced code blocks (` ```flowchart `, ` ```sequenceDiagram `, etc.) for each diagram in `docxContent.diagrams[]`
+- **`getDiagramTypes(typeId)` helper** in `lib/proposal-generator.cjs`: maps proposal type to diagram array (`project-proposal` → `[flowchart, gantt]`, `tech-architecture` → `[flowchart, sequenceDiagram, classDiagram]`, etc.)
+- **`.docx` Risk Register table**: Risk | Probability | Impact | Mitigation (5 placeholder rows)
+- **`.docx` Glossary table**: Term | Definition (4 placeholder rows)
+- `project-detail.docx` regenerated — 12 sections (added §8 Risk Register, §11 Glossary; previous §8–10 renumbered §9–12)
+- 17 new tests in `tests/unit/vp-enh041-proposal-docx-ai.test.js`; `vp-proposal-contracts.test.js` updated (+5 ENH-041 assertions)
+
+## [2.7.0] - 2026-04-10
+
+### Added (ENH-040 — Phase 69)
+- **`workflows/proposal.md` Step 2C Quality Brief**: 4 focused questions before AI generation — CTA, budget range, timeline constraint, decision-maker — stored in manifest `meta` field
+- **Manifest `meta` schema**: `cta`, `budget`, `timeline`, `decisionMaker` fields drive tone and content specificity
+- **AI Prompt Contract** in manifest_generation step: 8–15 word outcome-oriented bullets, 3–5 sentence speaker notes, concrete CTA on closing slide, avoids filler phrases
+- **`.pptx` templates: 5 distinct layouts** (ENH-040 Layer 1):
+  - `cover` — split panel (left charcoal + ViePilot mark, right title/subtitle/meta)
+  - `section` — left accent sidebar + heading bar + bullets
+  - `two-column` — heading + dual column content (comparisons, scope, competitive)
+  - `data` — heading + up to 3 metric callout boxes (large value + label + note)
+  - `closing` — full charcoal, prominent CTA text, accent bars top/bottom
+- **`.docx` template: structured tables + narrative** (ENH-040 Layer 3):
+  - **Timeline table**: Phase | Milestone/Deliverable | Duration | Dependencies (6 rows)
+  - **Budget/Investment table**: Line Item | Estimate | Notes (with TOTAL row)
+  - **Team table**: Role | Name/Background | Responsibility
+  - Narrative paragraphs for Executive Summary, Problem & Opportunity, Why Choose Us
+  - 10 sections + explicit `{{placeholder}}` instructions for AI to fill
+- All 4 `.pptx` stock templates regenerated (137–151 KB; prev 97–126 KB)
+- `project-detail.docx` regenerated (12 KB; prev 10 KB)
+
+### Tests
+- Added `tests/unit/vp-enh040-proposal-quality.test.js` (27 tests — workflow contracts, pptx layout coverage, docx structure)
+- Updated `tests/unit/vp-proposal-contracts.test.js` (+2 tests — quality brief + outcome-oriented rules)
+- Total: **660 → 689 tests**
+
+## [2.6.0] - 2026-04-10
+
+### Added (ENH-039 — Phase 68)
+- **`/vp-proposal --lang <code>`**: language selection for AI-generated content (ISO 639-1; e.g. `vi`, `en`, `ja`, `fr`, `zh`)
+  - If omitted: prompted with MRU suggestions from `~/.viepilot/config.json → proposal.recentLangs`
+  - Language is saved to MRU after each successful generation
+- **`/vp-proposal --lang-content-only`**: translate bullets, notes, and paragraphs; keep structural labels / section names in English
+- **MRU language history**: `~/.viepilot/config.json → proposal.recentLangs` (max 5, most recent first, deduped)
+- **`lib/viepilot-config.cjs`**: `getProposalLang()` + `recordProposalLang()` helpers; `DEFAULTS` extended with `proposal.recentLangs` + `proposal.defaultLang`
+- **`lib/proposal-generator.cjs`**: `buildLangInstruction(lang, contentOnly)` — builds AI prompt language instruction; no-op for English
+- **`workflows/proposal.md`**: Step 3b Language Selection (MRU prompt); `langInstruction` injection in manifest generation; `recordProposalLang` after confirm output
+- **`skills/vp-proposal/SKILL.md`**: `--lang` + `--lang-content-only` flags documented
+
+### Tests
+- Added `tests/unit/vp-enh039-proposal-lang.test.js` (13 tests — config helpers, buildLangInstruction, SKILL.md/workflow contracts)
+- Updated `tests/unit/vp-proposal-contracts.test.js` (+2 tests — --lang and --lang-content-only flag documentation)
+- Total: **645 → 660 tests**
+
+## [2.5.0] - 2026-04-11
+
+### Added (FEAT-016 — Phases 63–67)
+- **`/vp-proposal` skill**: convert brainstorm session (or direct brief) → professional proposal package
+  - `.pptx` presentation (ViePilot branded, dark navy/charcoal)
+  - `.docx` detailed document (10 sections: executive summary → appendix)
+  - `.md` Markdown source of truth
+  - Optional `.txt` Google Slides URL (`--slides` flag)
+- **4 proposal types**: `project-proposal` (10 slides), `tech-architecture` (12), `product-pitch` (12), `general` (8)
+- **`lib/proposal-generator.cjs`**: 2-tier template resolution (project `.viepilot/proposal-templates/` override → ViePilot stock fallback), context detection, type validation, output path builder
+- **`lib/google-slides-exporter.cjs`**: service account auth; lazy-loads `@googleapis/slides`; graceful error when package or credentials absent
+- **Stock templates**: `templates/proposal/pptx/` (4 files, dark navy `#1a1f36`/charcoal `#2d3142`, ViePilot branded) + `templates/proposal/docx/project-detail.docx`
+- **`scripts/gen-proposal-pptx.cjs`** + **`scripts/gen-proposal-docx.cjs`**: template generation scripts
+- **`skills/vp-proposal/SKILL.md`**: full skill definition; `--type`, `--from`, `--slides`, `--dry-run` flags
+- **`workflows/proposal.md`**: 10-step workflow; slide manifest schema; 4 proposal type structures; error handling
+- **`docs/user/features/proposal.md`**: full user guide with Google Slides 5-step setup guide
+- **`@googleapis/slides`** added as `optionalDependencies` (install not required unless using `--slides`)
+- **`pptxgenjs` + `docx`** added as runtime `dependencies`
+
+### Tests
+- Added `tests/unit/vp-proposal-contracts.test.js` (25 tests — skill/workflow files, generator exports, stock templates, graceful degradation)
+- Added `tests/unit/vp-proposal-core.test.js` (15 tests — resolveTemplate, validateType, detectBrainstormSession)
+- Total: 607 → **647 tests**
+
 ## [2.4.0] - 2026-04-10
 
 ### Added (FEAT-015 — Phase 62)

package/README.md

@@ -2,9 +2,9 @@
 
 **Autonomous Vibe Coding Framework / Bộ khung phát triển tự động có kiểm soát**
 
-[![Version](https://img.shields.io/badge/version-2.4.0-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-2.5.0-blue.svg)](CHANGELOG.md)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
-[![Skills](https://img.shields.io/badge/skills-16-purple.svg)](#skills-reference)
+[![Skills](https://img.shields.io/badge/skills-17-purple.svg)](#skills-reference)
 [![Workflows](https://img.shields.io/badge/workflows-12-orange.svg)](#workflows)
 [![Templates](https://img.shields.io/badge/templates-17-cyan.svg)](#templates)
 [![Tests](https://img.shields.io/badge/tests-607%20passing-brightgreen.svg)](tests/)
@@ -29,7 +29,7 @@ Nếu ViePilot giúp ích cho bạn, bạn có thể ủng hộ một ly cafe:
 | Chỉ số / Metric | Giá trị / Value |
 |-----------------|-----------------|
 | Total LOC | **~39,668+** (`.md`, `.js`, `.cjs`, `.yml`, `.json`, `.sh`; không gồm `node_modules`) |
-| Skills | **16** |
+| Skills | **17** |
 | Workflows | **12** |
 | Templates | **17** (Project: 12, Phase: 5) |
 | CLI Commands | **18** (`vp-tools` 17 subcommands + `viepilot` installer) |
@@ -43,7 +43,7 @@ Nếu ViePilot giúp ích cho bạn, bạn có thể ủng hộ một ly cafe:
 
 | Thành phần / Component | Số lượng / Count | Mô tả / Description |
 |------------------------|------------------|---------------------|
-| Skill Definitions | **16** | SKILL.md files với trigger, process, success criteria |
+| Skill Definitions | **17** | SKILL.md files với trigger, process, success criteria |
 | Workflow Files | **12** | Step-by-step execution guides |
 | Project Templates | 12 | AI-GUIDE, ARCHITECTURE, VIEPILOT-META, README, SYSTEM-RULES, etc. |
 | Phase Templates | 5 | SPEC, PHASE-STATE, TASK, VERIFICATION, SUMMARY |
@@ -60,7 +60,7 @@ Tổng thể / Overall:  ██████████████████
 
 | Lĩnh vực / Area | Trạng thái | Chi tiết |
 |-----------------|------------|----------|
-| Core Skills (16) | ✅ Hoàn thiện | brainstorm, crystallize, auto, pause, resume, status, info, request, evolve, docs, update, task, debug, rollback, audit, ui-components |
+| Core Skills (17) | ✅ Hoàn thiện | brainstorm, crystallize, auto, pause, resume, status, info, request, evolve, docs, update, task, debug, rollback, audit, ui-components, **proposal** |
 | Workflows (12) | ✅ Hoàn thiện | Full step-by-step guides với success criteria |
 | Project Templates (12) | ✅ Hoàn thiện | Placeholders cho customization (+ `VIEPILOT-META` FEAT-009) |
 | Phase Templates (5) | ✅ Hoàn thiện | Task tracking, verification, summary |
@@ -126,6 +126,7 @@ Tổng thể / Overall:  ██████████████████
 | `/vp-debug` | Debug có hệ thống với state tracking / Systematic debugging | "debug", "gỡ lỗi" | Debug |
 | `/vp-rollback` | Khôi phục về checkpoint / Rollback to checkpoint | "rollback", "revert" | Recovery |
 | `/vp-audit` | Kiểm tra sync docs vs implementation | "audit", "kiểm tra" | Quality |
+| `/vp-proposal` | Generate .pptx + .docx proposal package từ brainstorm | "proposal", "pitch", "presentation" | Deliver |
 
 ---
 

package/docs/brainstorm/session-2026-04-11.md

@@ -0,0 +1,194 @@
+# Brainstorm Session — 2026-04-11
+
+## Topic
+**vp-proposal** — Skill mới: Idea → Proposal Documents + Presentation files (.pptx, .docx)
+
+## Status
+Completed — Ready for `/vp-crystallize` / `/vp-request` → `/vp-evolve` → `/vp-auto`
+
+---
+
+## Problem Statement
+ViePilot hiện có thể đưa ý tưởng thành code nhưng chưa có cầu nối sang **tài liệu bán hàng / thuyết phục**. Developer cần trình bày dự án cho khách hàng, đối tác, nhà đầu tư — hiện phải tự làm thủ công PowerPoint/Word tốn nhiều thời gian.
+
+---
+
+## Solution: `/vp-proposal`
+
+Skill chuyển đổi ideas/brainstorm session → professional proposal package:
+- **Presentation** (`.pptx`) — thuyết trình trực tiếp
+- **Detail document** (`.docx`) — tài liệu chi tiết kèm theo
+- **Markdown summary** (`.md`) — source of truth, version-controlled
+- **Google Slides link** (optional `--slides`) — cloud sharing
+
+---
+
+## Decisions
+
+### D1: AI content generation
+Auto-generate từ brainstorm session notes (context-aware).
+- Nếu có `docs/brainstorm/session-*.md` → load latest session tự động làm input
+- Standalone mode: user cung cấp brief trực tiếp trong chat
+- Không cần user điền outline thủ công — AI extract + structure
+
+### D2: Template system (2-tier resolution)
+```
+Tier 1 (project override):  .viepilot/proposal-templates/{type}.pptx|docx
+Tier 2 (stock fallback):    {viepilot-install}/templates/proposal/pptx/{type}.pptx
+                             {viepilot-install}/templates/proposal/docx/{type}.docx
+```
+- Override chỉ ảnh hưởng project hiện tại
+- Stock templates ship theo npm package
+
+### D3: Proposal types (4 + 1 docx)
+| Type ID | Tên | Use case |
+|---------|-----|----------|
+| `project-proposal` | Project Proposal | Scope, timeline, budget cho khách hàng |
+| `tech-architecture` | Technical Architecture | Thiết kế hệ thống cho technical partner |
+| `product-pitch` | Product Pitch Deck | Investor / partner pitch |
+| `general` | General Proposal | Tổng quát, fallback |
+| `project-detail` (docx) | Project Detail Doc | Tài liệu chi tiết bổ sung cho tất cả loại trên |
+
+### D4: Output location
+```
+docs/proposals/
+├── {slug}-{date}.md          # Markdown source
+├── {slug}-{date}.pptx        # Presentation
+├── {slug}-{date}.docx        # Detail document
+└── {slug}-{date}-slides.txt  # Google Slides URL (nếu --slides)
+```
+
+### D5: Tech stack
+| Output | Package | Version | Downloads/wk |
+|--------|---------|---------|-------------|
+| `.pptx` | `pptxgenjs` | ^3.x | 1.8M |
+| `.docx` | `docx` | ^9.x | 3.5M |
+| Google Slides | `@googleapis/slides` | official | optional dep |
+
+### D6: Workflow integration
+- `c` — Context-aware: detect brainstorm session tự động OR standalone brief
+- Auto-detect: check `docs/brainstorm/session-*.md` → sort by date → load latest
+- User có thể override: `/vp-proposal --from session-2026-04-11.md`
+
+---
+
+## Architecture
+
+### New files
+```
+skills/vp-proposal/
+└── SKILL.md                          # Skill definition
+
+workflows/
+└── proposal.md                       # Step-by-step workflow
+
+lib/
+└── proposal-generator.cjs            # Core: template resolution + pptxgenjs + docx
+
+templates/proposal/
+├── pptx/
+│   ├── project-proposal.pptx         # ViePilot stock template
+│   ├── tech-architecture.pptx
+│   ├── product-pitch.pptx
+│   └── general.pptx
+└── docx/
+    └── project-detail.docx           # ViePilot stock .docx template
+```
+
+### Template resolution logic (lib/proposal-generator.cjs)
+```js
+function resolveTemplate(type, ext, projectRoot) {
+  const projectOverride = path.join(projectRoot, '.viepilot/proposal-templates', `${type}.${ext}`);
+  if (fs.existsSync(projectOverride)) return projectOverride;
+  return path.join(__dirname, '../templates/proposal', ext, `${type}.${ext}`);
+}
+```
+
+### Slide generation flow
+```
+/vp-proposal [--type project-proposal] [--slides]
+      │
+      ├─ 1. Load context (brainstorm session or user brief)
+      ├─ 2. AI structures content → JSON slide manifest
+      ├─ 3. resolveTemplate() → pick .pptx/.docx template
+      ├─ 4. pptxgenjs → write .pptx
+      ├─ 5. docx → write .docx
+      ├─ 6. Write .md summary
+      └─ 7. (--slides) Google Slides API upload → write URL
+```
+
+---
+
+## Open Questions
+
+- ~~OQ1~~: **Resolved** — Dark theme: navy/charcoal. Professional, tech feel.
+- ~~OQ2~~: **Resolved** — Flexible per type: project-proposal 10, tech-architecture 12, product-pitch 12, general 8.
+- ~~OQ3~~: **Resolved** — `optionalDependencies` — load on demand khi `--slides` flag, npm install không fail nếu thiếu.
+- ~~OQ4~~: **Resolved** — Skill-only `/vp-proposal`, nhất quán với các skill khác.
+
+---
+
+## Phases
+
+### Phase 1 — Core infrastructure
+- Add `pptxgenjs` + `docx` to `package.json` dependencies
+- `lib/proposal-generator.cjs`: template resolution + base pptx/docx writer
+- Unit tests: template resolution logic
+
+### Phase 2 — Skill + Workflow
+- `skills/vp-proposal/SKILL.md`
+- `workflows/proposal.md` — full step-by-step
+- Context detection: brainstorm session auto-load
+- 4 proposal types wired up
+
+### Phase 3 — Stock templates
+- Design + generate 4 stock `.pptx` templates (ViePilot branded)
+- 1 stock `.docx` template
+- Store in `templates/proposal/`
+
+### Phase 4 — Google Slides export (optional)
+- `--slides` flag
+- `@googleapis/slides` optional dependency
+- Service account auth guide in docs
+
+### Phase 5 — Tests + Docs
+- Jest contracts for proposal-generator
+- `docs/user/features/proposal.md`
+- Update `docs/skills-reference.md` + `README.md`
+
+---
+
+## Research Notes
+
+### pptxgenjs
+- MIT, zero runtime dependencies
+- Supports Slide Masters for branded templates
+- HTML-to-PPTX in 1 line
+- Template injection: load existing .pptx → inject content
+
+### docx (by Dolan Miu)
+- MIT, 3.5M downloads/week
+- Declarative API: `new Document({ sections: [...] })`
+- Supports tables, images, headings, lists
+- Version 9.6.1, actively maintained
+
+### Google Slides API
+- Official `@googleapis/slides` Node.js client
+- Service account = no browser auth for CLI
+- Template-based: create in Slides → replace placeholders via API
+- Optional: only needed for `--slides` flag
+
+---
+
+## Project meta intake (FEAT-009)
+Waiver — this is the ViePilot framework repo itself; profile binding already exists.
+
+---
+
+## Session Summary
+- **Feasibility**: HIGH ✅
+- **Dependencies**: 2 well-maintained npm packages (pptxgenjs + docx), both MIT
+- **Complexity**: Medium — template system + AI content structuring + 2 file formats
+- **Estimated phases**: 5
+- **Suggested ID**: FEAT-016
+- **Target version**: 2.5.0

package/docs/skills-reference.md

@@ -467,3 +467,49 @@ CHANGELOG.md (updated)
 ### Lưu ý
 - Trong repo **application** có `node_modules/viepilot`, update mặc định có thể target **local** — dùng **`--global`** nếu chỉ muốn global.
 - Luồng an toàn: `vp-tools update --dry-run` → sau đó `vp-tools update --yes` (hoặc `--global --yes`).
+
+---
+
+## /vp-proposal
+
+**Purpose**: Generate professional proposal packages (.pptx + .docx + .md) from brainstorm sessions or direct briefs.
+
+**Triggers**: "proposal", "pitch deck", "presentation", "tài liệu đề xuất"
+
+### Proposal Types
+| Type | Slides | Use case |
+|------|--------|----------|
+| `project-proposal` | 10 | Client delivery — scope, timeline, budget |
+| `tech-architecture` | 12 | Technical partners — system design |
+| `product-pitch` | 12 | Investors / partners — pitch |
+| `general` | 8 | Any audience — flexible |
+
+### Flags
+| Flag | Description |
+|------|-------------|
+| `--type <id>` | Proposal type ID. If omitted: guided menu. |
+| `--from <file>` | Explicit brainstorm session file to use |
+| `--slides` | Upload to Google Slides after generation (requires service account) |
+| `--dry-run` | Print slide manifest; no files written |
+
+### Output
+```
+docs/proposals/
+├── {slug}-{date}.md      Markdown source
+├── {slug}-{date}.pptx    Presentation
+├── {slug}-{date}.docx    Detailed document
+└── {slug}-{date}-slides.txt  Google Slides URL (--slides only)
+```
+
+### Template Override
+Place custom `.pptx`/`.docx` files in `.viepilot/proposal-templates/` to override stock ViePilot templates for a specific project.
+
+### Examples
+```
+/vp-proposal                              Auto-detect session + guided type selection
+/vp-proposal --type product-pitch         12-slide investor pitch
+/vp-proposal --type project-proposal --slides  + upload to Google Slides
+/vp-proposal --dry-run                    Preview manifest only
+```
+
+Full guide: `docs/user/features/proposal.md`

package/docs/user/features/proposal.md

@@ -0,0 +1,196 @@
+# vp-proposal — Proposal Package Generator
+
+Generate professional proposal packages directly from your ViePilot brainstorm sessions.
+
+---
+
+## Overview
+
+`/vp-proposal` converts a brainstorm session (or a direct brief) into three synchronized files:
+
+| File | Format | Purpose |
+|------|--------|---------|
+| `{slug}-{date}.md` | Markdown | Source of truth, version-controlled |
+| `{slug}-{date}.pptx` | PowerPoint | Presentation (direct delivery) |
+| `{slug}-{date}.docx` | Word | Detailed supporting document |
+| `{slug}-{date}-slides.txt` | Text | Google Slides URL (with `--slides` flag) |
+
+All files are written to `docs/proposals/` in your project.
+
+---
+
+## Quick Start
+
+```bash
+# Auto-detects latest brainstorm session
+/vp-proposal
+
+# Specify type directly
+/vp-proposal --type product-pitch
+
+# With Google Slides upload
+/vp-proposal --type project-proposal --slides
+
+# Preview slide manifest without writing files
+/vp-proposal --dry-run
+```
+
+---
+
+## Proposal Types
+
+| Type ID | Name | Slides | Best for |
+|---------|------|--------|----------|
+| `project-proposal` | Project Proposal | 10 | Client delivery — scope, timeline, budget |
+| `tech-architecture` | Technical Architecture | 12 | Technical partners — system design |
+| `product-pitch` | Product Pitch Deck | 12 | Investors / partners — pitch |
+| `general` | General Proposal | 8 | Any audience — flexible structure |
+
+---
+
+## Flags
+
+| Flag | Description |
+|------|-------------|
+| `--type <id>` | Proposal type (see table above). If omitted: guided menu. |
+| `--from <file>` | Explicit brainstorm session: `--from docs/brainstorm/session-2026-04-11.md` |
+| `--slides` | Upload generated .pptx to Google Slides after generation |
+| `--dry-run` | Show slide manifest (JSON) without writing any files |
+
+---
+
+## Context Detection
+
+`/vp-proposal` automatically loads the most recent brainstorm session:
+
+1. Scans `docs/brainstorm/session-*.md`
+2. Sorts descending by filename (ISO date format)
+3. Loads the latest session as proposal content
+
+**Override:** use `--from <session-file>` to specify a different session.
+
+**Standalone mode:** if no session exists, you'll be prompted for a brief:
+- Project name
+- One-line description
+- Target audience
+- 3–5 key points
+
+---
+
+## Template Override
+
+ViePilot ships stock templates (dark navy/charcoal, ViePilot branded).
+To use your own branded templates for a specific project:
+
+```
+your-project/
+└── .viepilot/
+    └── proposal-templates/
+        ├── project-proposal.pptx    ← overrides stock
+        ├── tech-architecture.pptx
+        ├── product-pitch.pptx
+        ├── general.pptx
+        └── project-detail.docx
+```
+
+**Resolution order:**
+1. `.viepilot/proposal-templates/{type}.pptx` (project-level override)
+2. `{viepilot-install}/templates/proposal/pptx/{type}.pptx` (ViePilot stock)
+
+The override only applies to the project where the file is placed.
+
+---
+
+## Output Structure
+
+```
+docs/proposals/
+├── my-project-2026-04-11.md      # Markdown source of truth
+├── my-project-2026-04-11.pptx    # Presentation
+├── my-project-2026-04-11.docx    # Detailed document
+└── my-project-2026-04-11-slides.txt  # Google Slides URL (if --slides)
+```
+
+The `.md` file is the diff-friendly source. The `.pptx` and `.docx` are generated from it and can be regenerated at any time.
+
+---
+
+## Google Slides Export
+
+Use the `--slides` flag to automatically upload the generated `.pptx` to Google Slides.
+
+### Setup (one-time)
+
+**Step 1: Create a Google Cloud project**
+1. Go to [console.cloud.google.com](https://console.cloud.google.com)
+2. Create a new project (or select an existing one)
+
+**Step 2: Enable APIs**
+1. Navigate to **APIs & Services → Library**
+2. Enable **Google Drive API**
+3. Enable **Google Slides API**
+
+**Step 3: Create a Service Account**
+1. Go to **APIs & Services → Credentials**
+2. Click **Create Credentials → Service Account**
+3. Fill in name (e.g., `viepilot-proposal`)
+4. Click **Done**
+5. Click the new service account → **Keys** tab → **Add Key → Create new key (JSON)**
+6. Save the downloaded JSON file securely (e.g., `~/.config/viepilot-gcp-key.json`)
+
+**Step 4: Set environment variable**
+```bash
+export GOOGLE_APPLICATION_CREDENTIALS=/path/to/your-service-account-key.json
+
+# Add to ~/.zshrc or ~/.bashrc to persist:
+echo 'export GOOGLE_APPLICATION_CREDENTIALS=~/.config/viepilot-gcp-key.json' >> ~/.zshrc
+```
+
+**Step 5: Install the optional dependency**
+```bash
+npm install @googleapis/slides
+```
+
+### Usage
+```bash
+/vp-proposal --type product-pitch --slides
+# Output: docs/proposals/my-project-2026-04-11-slides.txt
+# Content: https://docs.google.com/presentation/d/{id}/edit
+```
+
+### Notes
+- The uploaded presentation retains the `.pptx` layout (converted by Google Drive)
+- Upload failures are non-fatal — the `.pptx`, `.docx`, and `.md` files are always written first
+- The service account needs no special permissions beyond the API scopes
+
+---
+
+## Examples
+
+### Client proposal from brainstorm session
+```
+/vp-proposal --type project-proposal
+→ Auto-loads docs/brainstorm/session-2026-04-11.md
+→ Generates 10-slide project proposal
+```
+
+### Investor pitch standalone
+```
+/vp-proposal --type product-pitch
+→ No session found — prompts for brief
+→ Generates 12-slide pitch deck
+```
+
+### Architecture review with Google Slides
+```
+/vp-proposal --type tech-architecture --slides
+→ Generates 12-slide architecture proposal + uploads to Google Slides
+→ Writes URL to docs/proposals/*-slides.txt
+```
+
+### Preview without writing files
+```
+/vp-proposal --dry-run
+→ Prints JSON slide manifest to console
+→ No files written
+```