careervivid 1.1.0 → 1.1.2

package/README.md

@@ -1,189 +1,327 @@
-# CareerVivid CLI
+# careervivid · CLI
 
-Official command-line interface for [CareerVivid](https://careervivid.app) — publish articles, architecture diagrams, and portfolio updates directly from your terminal or an AI coding agent.
+> **Publish technical articles, architecture diagrams, and portfolio updates to [CareerVivid](https://careervivid.app) — directly from your terminal or AI agent.**
+
+[![npm version](https://img.shields.io/npm/v/careervivid?color=0ea5e9&label=careervivid)](https://www.npmjs.com/package/careervivid)
+[![License: MIT](https://img.shields.io/badge/license-MIT-brightgreen)](LICENSE)
+[![Node ≥18](https://img.shields.io/badge/node-%3E%3D18-blue)](https://nodejs.org)
 
 ---
 
-## Quick Start
+## Table of Contents
 
-```bash
-npm install -g careervivid
-cv auth set-key
-cv publish article.md
-```
+- [Quick Start](#quick-start)
+- [Commands](#commands)
+  - [cv publish](#cv-publish)
+  - [cv whiteboard](#cv-whiteboard)
+  - [cv auth](#cv-auth)
+  - [cv config](#cv-config)
+- [Whiteboard Templates](#whiteboard-templates)
+- [AI Agent Integration](#ai-agent-integration)
+- [Updating](#updating)
+- [Troubleshooting](#troubleshooting)
 
 ---
 
-## Installation
+## Quick Start
 
 ```bash
-# Global install (recommended)
+# 1. Install globally
 npm install -g careervivid
 
-# Project-local (for CI/CD and AI agents)
-npm install --save-dev careervivid
-npx cv publish article.md
-```
+# 2. Save your API key (get it at careervivid.app/developer)
+cv auth set-key cv_live_YOUR_KEY_HERE
 
----
+# 3. Publish an article
+cv publish my-article.md --tags "typescript,react"
 
-## Authentication
+# 4. Create & publish an architecture diagram
+cv whiteboard new my-arch --template system-arch
+cv whiteboard publish my-arch.mmd --title "System Architecture"
+```
 
-Get your API key at [careervivid.app/#/developer](https://careervivid.app/#/developer).
+---
 
-```bash
-# Interactive setup
-cv auth set-key
+## Commands
 
-# Or pass directly (no prompts)
-cv auth set-key cv_live_your_key_here
+### `cv publish`
 
-# Verify it works
-cv auth check
+Publish a Markdown article or Mermaid diagram file to your CareerVivid portfolio.
 
-# See current config
-cv auth whoami
 ```
+cv publish <file> [options]
+cv publish -       (read from stdin)
+```
+
+| Option | Description |
+|---|---|
+| `-t, --title <title>` | Post title (auto-inferred from first `#` heading if omitted) |
+| `--type <type>` | `article` \| `whiteboard` (auto-inferred from file extension) |
+| `--format <format>` | `markdown` \| `mermaid` (auto-inferred from file extension) |
+| `--tags <tags>` | Comma-separated tags, e.g. `typescript,firebase,react` |
+| `--cover <url>` | URL to a cover image |
+| `--dry-run` | Validate payload without publishing |
+| `--json` | Machine-readable JSON output (ideal for AI agents) |
 
-Your key is stored in `~/.careervividrc.json` with `chmod 600` permissions. It is never printed to stdout.
+**Examples:**
 
-**Alternatively**, set the `CV_API_KEY` environment variable (takes priority over the config file):
 ```bash
-export CV_API_KEY=cv_live_...
+# Publish a Markdown article (title auto-detected from # heading)
+cv publish article.md
+
+# Publish with tags and a custom title
+cv publish article.md --title "How I Built a CLI in TypeScript" --tags "node,typescript,cli"
+
+# Publish a Mermaid diagram as a whiteboard
+cv publish architecture.mmd --title "System Architecture"
+
+# Pipe from stdin — perfect for AI agents
+cat writeup.md | cv publish - --title "Architecture Breakdown" --json
+
+# Dry-run to validate before publishing
+cv publish article.md --dry-run
 ```
 
 ---
 
-## Publishing Content
+### `cv whiteboard`
 
-### Publish a Markdown article
+Create and publish **Mermaid architecture diagrams** without any extra packages. All templates are built into the `careervivid` CLI.
 
-```bash
-cv publish article.md
-cv publish article.md --title "My Custom Title" --tags "typescript,firebase,saas"
-```
+#### `cv whiteboard new`
 
-The title is automatically inferred from the first `# Heading` in your file.
+Scaffold a new `.mmd` diagram file from a built-in template.
 
-### Publish a Mermaid diagram
+```
+cv whiteboard new [filename] [options]
+```
+
+| Option | Description |
+|---|---|
+| `--template <name>` | Template to use (see [Whiteboard Templates](#whiteboard-templates)) |
+| `--print` | Print the template to stdout instead of writing a file |
 
 ```bash
-cv publish diagram.mmd --type whiteboard
+# Interactive wizard — picks template and filename for you
+cv whiteboard new
+
+# Non-interactive — specify template and filename directly
+cv whiteboard new my-diagram --template system-arch
+
+# Preview a template without creating any file
+cv whiteboard new --template ci-cd --print
 ```
 
-Files with `.mmd` or `.mermaid` extensions are automatically detected as Mermaid diagrams.
+#### `cv whiteboard publish`
+
+Publish an existing `.mmd` file as a whiteboard post.
+
+```
+cv whiteboard publish <file> [options]
+```
 
-### Publish from stdin (pipe-friendly for AI agents)
+| Option | Description |
+|---|---|
+| `-t, --title <title>` | Diagram title (required) |
+| `--tags <tags>` | Comma-separated tags |
+| `--dry-run` | Validate without publishing |
+| `--json` | Machine-readable JSON output |
 
 ```bash
-cat article.md | cv publish - --title "Architecture Deep Dive"
-echo "# My Post\n\nHello world!" | cv publish - --tags "ai,demo"
+cv whiteboard publish my-diagram.mmd --title "CI/CD Pipeline" --tags "devops,cicd"
 ```
 
-### Dry run (validate without publishing)
+#### `cv whiteboard list-templates`
+
+Print all available built-in Mermaid templates.
 
 ```bash
-cv publish article.md --dry-run
+cv whiteboard list-templates
 ```
 
-### Machine-readable JSON output (for AI agents and scripts)
+---
+
+### `cv auth`
 
-Every command supports `--json`:
+Manage your CareerVivid API key. Get your key at [careervivid.app/developer](https://careervivid.app/developer).
+
+| Subcommand | Description |
+|---|---|
+| `cv auth set-key <key>` | Save your API key to `~/.careervividrc.json` |
+| `cv auth check` | Verify that your saved key is valid |
+| `cv auth remove` | Remove the saved key |
+| `cv auth whoami` | Show the currently authenticated user |
+
+The key is stored at `~/.careervividrc.json` with `chmod 600` permissions. You can also pass the key via the `CV_API_KEY` environment variable instead of saving it locally.
 
 ```bash
-cv publish article.md --json
-# → {"success":true,"postId":"abc123","url":"https://careervivid.app/community/post/abc123"}
+# Save key
+cv auth set-key cv_live_YOUR_KEY_HERE
 
-cat article.md | cv publish - --title "Post" --json
-# → {"success":true,"postId":"abc123","url":"..."}
+# Verify
+cv auth check
+# ✔  Authenticated as Jiawen Zhu (jiawen@careervivid.app)
+
+# Use env var instead of a saved key
+CV_API_KEY=cv_live_YOUR_KEY_HERE cv publish article.md
 ```
 
 ---
 
-## Command Reference
+### `cv config`
 
-```
-cv publish [file]
-  [file]             Path to a .md / .mmd file, or "-" to read stdin
-  --title <title>    Post title (required for stdin / if no # heading)
-  --type             article | whiteboard  (default: inferred)
-  --format           markdown | mermaid    (default: inferred from extension)
-  --tags <tags>      Comma-separated tags, max 5
-  --cover <url>      URL to a cover image
-  --dry-run          Validate without publishing
-  --json             Machine-readable output
+View and modify CLI configuration stored at `~/.careervividrc.json`.
 
-cv auth set-key [apiKey]
-cv auth check
-cv auth whoami
-cv auth revoke
+| Subcommand | Description |
+|---|---|
+| `cv config show` | Print the full config |
+| `cv config get <key>` | Print a single config value |
+| `cv config set <key> <value>` | Update a config value |
 
+```bash
 cv config show
-cv config get <key>         (keys: apiKey, apiUrl)
-cv config set <key> <val>
+cv config get apiKey
+cv config set apiUrl https://careervivid.app/api/publish
 ```
 
 ---
 
-## AI Agent & MCP Integration
+## Whiteboard Templates
 
-### With Cursor / Claude Desktop (MCP)
+Run `cv whiteboard list-templates` to see all templates. Available out of the box:
 
-The [MCP server](../mcp-server/) is the recommended way to integrate with AI coding agents. See `mcp-server/README.md`.
+| Template | Description |
+|---|---|
+| `flowchart` | Generic flowchart / process diagram |
+| `system-arch` | System architecture (client → API → DB) |
+| `tech-stack` | Full technology stack diagram |
+| `user-journey` | Sequence diagram (user ↔ API ↔ DB) |
+| `er-diagram` | Entity-relationship / database schema |
+| `git-flow` | Git branching and release flow |
+| `ci-cd` | CI/CD pipeline (lint → test → build → deploy) |
+| `mindmap` | Mind map / concept breakdown |
 
-### Direct CLI from an AI agent
+**Workflow:**
 
 ```bash
-# Agent publishes an article it just wrote:
-echo "${ARTICLE_CONTENT}" | cv publish - \
-  --title "${TITLE}" \
-  --tags "${TAGS}" \
-  --json
+# 1. Pick a template and scaffold the file
+cv whiteboard new my-pipeline --template ci-cd
 
-# Agent parses the JSON response:
-# {"success":true,"postId":"abc123","url":"https://careervivid.app/community/post/abc123"}
-```
+# 2. Edit it in your editor (or let your AI agent edit it)
+code my-pipeline.mmd
 
-For full agentic pipelines, prefer the MCP server — it integrates natively with AI tool calling.
+# 3. Publish to CareerVivid
+cv whiteboard publish my-pipeline.mmd --title "Our CI/CD Pipeline"
+# ✔  Whiteboard published!
+#    URL: https://careervivid.app/community/post/abc123
+```
 
 ---
 
-## Environment Variables
+## AI Agent Integration
+
+The CLI is designed to be **AI-agent-friendly**. Use `--json` for structured output and pipe from stdin for fully automated publishing flows.
 
-| Variable | Description |
-|----------|-------------|
-| `CV_API_KEY` | API key (overrides config file) |
-| `CV_API_URL` | Override the publish endpoint (for self-hosting or staging) |
+### Copy this into your AI agent's system prompt:
+
+```
+# CareerVivid AI Publishing Rules
+
+You are an expert technical writer and senior software architect.
+Your secondary directive — after writing and fixing code — is to
+proactively help the user document their work and build their
+CareerVivid portfolio using the local `cv` CLI.
+
+## 1. Triggers (When to Propose a Post)
+Do not wait for the user to ask. Propose a CareerVivid post when:
+- You complete a significant feature, module, or architecture.
+- You perform a complex refactor or solve a difficult bug.
+- The user says "document this" or "publish to CareerVivid".
+
+## 2. Security (CRITICAL)
+- NEVER include actual API keys, secrets, or internal IPs.
+- Replace sensitive values with placeholder variables.
+
+## 3. Content Format
+- Architecture / data flows → Mermaid diagram (.mmd)
+- Tutorials / devlogs → Markdown article (.md)
+
+## 4. Consent Gate (DO NOT SKIP)
+1. Generate and save the file locally.
+2. Tell the user: "I drafted a CareerVivid post. Review and confirm."
+3. Wait for explicit confirmation before running cv publish.
+
+## 5. CLI Commands
+cv publish ./article.md --title "Title" --json
+cv whiteboard publish ./diagram.mmd --title "Diagram" --json
+```
+
+### Cursor / Claude Desktop (MCP)
+
+For deeper integration using the Model Context Protocol, see the [Integration Guide](https://careervivid.app/developer) on your Developer Settings page.
+
+### Automated Pipeline Example
+
+```bash
+# Generate markdown from your AI agent and publish directly
+echo "# My Architecture\n\nExplains the new service..." \
+  | cv publish - --title "New Service Explained" --tags "architecture" --json
+
+# Output:
+# { "postId": "abc123", "url": "https://careervivid.app/community/post/abc123" }
+```
 
 ---
 
-## Configuration File
+## Updating
+
+```bash
+npm install -g careervivid
+```
 
-Location: `~/.careervividrc.json` (mode 600 — readable only by your user)
+Check your current version:
 
-```json
-{
-  "apiKey": "cv_live_...",
-  "apiUrl": "https://careervivid.app/api/publish"
-}
+```bash
+cv -v
 ```
 
 ---
 
-## Building from Source
+## Troubleshooting
+
+**`cv: command not found`**
+```bash
+# Check npm global bin is in your PATH
+npm config get prefix
+# Add <prefix>/bin to your PATH in ~/.zshrc or ~/.bashrc
+```
+
+**`Unauthorized` error**
+```bash
+# Re-check your key is saved correctly
+cv auth check
+
+# Or set it directly via env var
+CV_API_KEY=cv_live_YOUR_KEY cv publish article.md
+```
 
+**Permission denied on `~/.careervividrc.json`**
 ```bash
-git clone https://github.com/Jastalk/CareerVivid
-cd CareerVivid/cli
-npm install && npm run build
-npm install -g .
+chmod 600 ~/.careervividrc.json
 ```
 
+**Mermaid diagram not rendering**
+Run `cv whiteboard new --template flowchart --print` to validate your Mermaid syntax against a known-good example. The CareerVivid web app renders Mermaid live in the post detail view.
+
 ---
 
-## Security
+## Resources
+
+- 🌐 [careervivid.app](https://careervivid.app)
+- 🔑 [Developer Settings & API Key](https://careervivid.app/developer)
+- 🐛 [Report an Issue](https://github.com/Jastalk/CareerVivid/issues)
+- 📦 [npm Package](https://www.npmjs.com/package/careervivid)
+
+---
 
-- API keys are **never** written to `stdout` — only `stderr` diagnostics and masked previews
-- The config file is created with `chmod 600`
-- Never commit `~/.careervividrc.json` or `CV_API_KEY` to version control
-- Revoke a compromised key immediately at [careervivid.app/#/developer](https://careervivid.app/#/developer)
+MIT License © CareerVivid

package/dist/index.js

@@ -24,7 +24,7 @@ const program = new Command();
 program
     .name("cv")
     .description("CareerVivid CLI — publish articles, diagrams, and portfolio updates from your terminal or AI agent")
-    .version("1.1.0", "-v, --version", "Print CLI version")
+    .version("1.1.2", "-v, --version", "Print CLI version")
     .helpOption("-h, --help", "Show help");
 registerAuthCommand(program);
 registerPublishCommand(program);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "careervivid",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Official CLI for CareerVivid — publish articles, diagrams, and portfolio updates from your terminal or AI agent",
   "type": "module",
   "bin": {