viepilot 2.1.0 → 2.12.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/adapters.md

@@ -0,0 +1,74 @@
+# Supported Adapters
+
+ViePilot supports multiple AI coding platforms via its adapter system (FEAT-013). Each adapter defines where skills and workflows are installed on your machine.
+
+## Supported Platforms
+
+| Adapter ID | Platform | Skills dir | ViePilot dir | Hooks | Skill syntax |
+|------------|----------|------------|--------------|-------|--------------|
+| `claude-code` | Claude Code *(default)* | `~/.claude/skills/` | `~/.claude/viepilot/` | ✅ Stop, PreToolUse, … | `/vp-status` |
+| `cursor-agent` / `cursor-ide` | Cursor | `~/.cursor/skills/` | `~/.cursor/viepilot/` | — | `/vp-status` |
+| `antigravity` | Google Antigravity | `~/.antigravity/skills/` | `~/.antigravity/viepilot/` | — | `/vp-status` |
+| `codex` | OpenAI Codex CLI | `~/.codex/skills/` | `~/.codex/viepilot/` | — | `$vp-status` |
+
+> **Note — Codex invocation syntax:** OpenAI Codex CLI uses `$skill-name` to invoke skills (e.g. `$vp-status`, `$vp-brainstorm`). The `/command` prefix is reserved for Codex built-in controls (`/plan`, `/clear`, `/diff`, etc.). SKILL.md file format is fully compatible — no changes needed to skill content.
+
+## Install for a specific platform
+
+```bash
+# Claude Code (default)
+viepilot install
+
+# Cursor Agent
+viepilot install --target cursor-agent
+
+# Google Antigravity
+viepilot install --target antigravity
+
+# OpenAI Codex CLI
+viepilot install --target codex
+
+# Multiple targets at once
+viepilot install --target claude-code,antigravity
+```
+
+## How path resolution works (ENH-035)
+
+Skill source files use the neutral placeholder `{envToolDir}` in `execution_context` blocks:
+
+```
+@$HOME/{envToolDir}/workflows/autonomous.md
+```
+
+At install time, `{envToolDir}` is replaced with each adapter's `executionContextBase`:
+- `claude-code` → `.claude/viepilot`
+- `cursor` → `.cursor/viepilot`
+- `antigravity` → `.antigravity/viepilot`
+- `codex` → `.codex/viepilot`
+
+## Adding a new adapter
+
+Create `lib/adapters/{name}.cjs`:
+
+```js
+module.exports = {
+  id: 'myplatform',
+  name: 'My Platform',
+  skillsDir:   (home) => path.join(home, '.myplatform', 'skills'),
+  viepilotDir: (home) => path.join(home, '.myplatform', 'viepilot'),
+  executionContextBase: '.myplatform/viepilot',  // {envToolDir} resolves to this
+  postInstallHint: 'Open project and run /vp-status',  // or $vp-status if platform uses $ prefix
+  hooks: { configFile: null, schema: 'myplatform', supportedEvents: [] },
+  installSubdirs: ['workflows', 'templates/project', 'templates/phase',
+                   'templates/architect', 'bin', 'lib', 'ui-components'],
+  isAvailable: (home) => fs.existsSync(path.join(home, '.myplatform'))
+};
+```
+
+Register in `lib/adapters/index.cjs`:
+
+```js
+'myplatform': require('./myplatform.cjs'),
+```
+
+No `pathRewrite` field needed — `{envToolDir}` substitution is handled automatically.

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
+```

package/lib/adapters/antigravity.cjs

@@ -0,0 +1,33 @@
+'use strict';
+const os = require('os');
+const path = require('path');
+const fs = require('fs');
+
+module.exports = {
+  id: 'antigravity',
+  name: 'Antigravity',
+  skillsDir:   (home) => path.join(home, '.antigravity', 'skills'),
+  viepilotDir: (home) => path.join(home, '.antigravity', 'viepilot'),
+  // {envToolDir} in SKILL.md files resolves to this value at install time (ENH-035)
+  executionContextBase: '.antigravity/viepilot',
+  // Post-install hint shown in "Next actions" after viepilot install
+  postInstallHint: 'Open project and run /vp-status',
+  hooks: {
+    configFile: null,       // Antigravity has no programmatic hooks system
+    schema: 'antigravity',
+    supportedEvents: []
+  },
+  installSubdirs: [
+    'workflows',
+    path.join('templates', 'project'),
+    path.join('templates', 'phase'),
+    path.join('templates', 'architect'),
+    'bin',
+    'lib',
+    'ui-components'
+  ],
+  isAvailable: (home) => {
+    const h = home || os.homedir();
+    return fs.existsSync(path.join(h, '.antigravity'));
+  }
+};

package/lib/adapters/claude-code.cjs

@@ -11,8 +11,8 @@ module.exports = {
   viepilotDir: (home) => path.join(home, '.claude', 'viepilot'),
   // execution_context base for skill .md files
   executionContextBase: '.claude/viepilot',
-  // Path rewrite rule: when mirroring skills, rewrite from → to in *.md files
-  pathRewrite: { from: '.cursor/viepilot', to: '.claude/viepilot' },
+  // Post-install hint shown in "Next actions" after viepilot install
+  postInstallHint: 'Restart session so ~/.claude/skills/vp-* is picked up; then /vp-status',
   // Hooks configuration (Claude Code settings.json)
   hooks: {
     configFile: (home) => path.join(home, '.claude', 'settings.json'),

package/lib/adapters/codex.cjs

@@ -0,0 +1,34 @@
+'use strict';
+const os = require('os');
+const path = require('path');
+const fs = require('fs');
+
+module.exports = {
+  id: 'codex',
+  name: 'Codex',
+  skillsDir:   (home) => path.join(home, '.codex', 'skills'),
+  viepilotDir: (home) => path.join(home, '.codex', 'viepilot'),
+  // {envToolDir} in SKILL.md files resolves to this value at install time (ENH-035)
+  executionContextBase: '.codex/viepilot',
+  // NOTE: Codex uses $skill-name syntax (not /skill-name like other adapters)
+  // Codex reserves /command for built-in system controls (/plan, /clear, /diff, etc.)
+  postInstallHint: 'Open project and type $vp-status to get started',
+  hooks: {
+    configFile: null,       // Codex uses AGENTS.md convention, not programmatic hooks
+    schema: 'codex',
+    supportedEvents: []
+  },
+  installSubdirs: [
+    'workflows',
+    path.join('templates', 'project'),
+    path.join('templates', 'phase'),
+    path.join('templates', 'architect'),
+    'bin',
+    'lib',
+    'ui-components'
+  ],
+  isAvailable: (home) => {
+    const h = home || os.homedir();
+    return fs.existsSync(path.join(h, '.codex'));
+  }
+};

package/lib/adapters/cursor.cjs

@@ -9,7 +9,8 @@ module.exports = {
   skillsDir:   (home) => path.join(home, '.cursor', 'skills'),
   viepilotDir: (home) => path.join(home, '.cursor', 'viepilot'),
   executionContextBase: '.cursor/viepilot',
-  pathRewrite: null,     // no rewrite needed (source is cursor-first)
+  // Post-install hint shown in "Next actions" after viepilot install
+  postInstallHint: 'Open project and run /vp-status',
   hooks: {
     configFile: null,    // Cursor uses .cursorrules/MDC, not settings.json hooks
     schema: 'cursor',

package/lib/adapters/index.cjs

@@ -2,8 +2,10 @@
 const adapters = {
   'claude-code':  require('./claude-code.cjs'),
   'cursor':       require('./cursor.cjs'),
-  'cursor-agent': require('./cursor.cjs'),  // alias
-  'cursor-ide':   require('./cursor.cjs'),  // alias
+  'cursor-agent': require('./cursor.cjs'),      // alias
+  'cursor-ide':   require('./cursor.cjs'),      // alias
+  'antigravity':  require('./antigravity.cjs'),
+  'codex':        require('./codex.cjs'),
 };
 
 /**

package/lib/google-slides-exporter.cjs

@@ -0,0 +1,80 @@
+'use strict';
+/**
+ * google-slides-exporter.cjs
+ * Uploads a .pptx file to Google Drive and converts it to a Google Slides presentation.
+ *
+ * Requirements (optional — only needed when --slides flag is used):
+ *   npm install @googleapis/slides
+ *   export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json
+ *
+ * See docs/user/features/proposal.md → "Google Slides Export" for setup guide.
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+/**
+ * Upload a local .pptx file to Google Drive and convert to Google Slides.
+ *
+ * @param {string} pptxPath  Absolute path to the .pptx file
+ * @param {string} title     Title for the Google Slides presentation
+ * @returns {Promise<string>} Public edit URL of the created presentation
+ */
+async function uploadToSlides(pptxPath, title) {
+  // Lazy-load @googleapis/slides — it is an optionalDependency.
+  // Provide a clear, actionable error when the package is not installed.
+  let googleApis;
+  try {
+    googleApis = require('googleapis');
+  } catch {
+    throw new Error(
+      'Google Slides export requires the @googleapis/slides package.\n\n' +
+      'Install it:\n' +
+      '  npm install @googleapis/slides\n\n' +
+      'Then set your service account credentials:\n' +
+      '  export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json\n\n' +
+      'See: docs/user/features/proposal.md → "Google Slides Export"'
+    );
+  }
+
+  const { google } = googleApis;
+
+  // Verify credentials env var is set before attempting auth
+  if (!process.env.GOOGLE_APPLICATION_CREDENTIALS) {
+    throw new Error(
+      'GOOGLE_APPLICATION_CREDENTIALS environment variable is not set.\n\n' +
+      'Set it to the path of your Google service account JSON key:\n' +
+      '  export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json\n\n' +
+      'See: docs/user/features/proposal.md → "Google Slides Export"'
+    );
+  }
+
+  // Authenticate via service account (no browser interaction required)
+  const auth = new google.auth.GoogleAuth({
+    scopes: [
+      'https://www.googleapis.com/auth/drive',
+      'https://www.googleapis.com/auth/presentations',
+    ],
+  });
+
+  const authClient = await auth.getClient();
+  const drive = google.drive({ version: 'v3', auth: authClient });
+
+  // Upload .pptx and request conversion to Google Slides format
+  const { data: file } = await drive.files.create({
+    requestBody: {
+      name: title,
+      mimeType: 'application/vnd.google-apps.presentation',
+    },
+    media: {
+      mimeType:
+        'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+      body: fs.createReadStream(pptxPath),
+    },
+    fields: 'id',
+  });
+
+  return `https://docs.google.com/presentation/d/${file.id}/edit`;
+}
+
+module.exports = { uploadToSlides };