@loviusc/sa-spec 0.2.5 → 0.2.7

package/README.en.md

@@ -22,7 +22,7 @@
 
 Before code-generation AI tools (OpenSpec, Claude Code, OpenAI Codex, Gemini CLI, Cursor) start implementation, `sa-spec` clarifies scopes, boundaries, data schemas, API contracts, permission matrices, and acceptance criteria to ensure that subsequent coding proceeds within safe, well-defined boundaries.
 
-The AI workflow operates on four standard commands (with shorthand aliases):
+The AI workflow operates on five standard commands (with shorthand aliases):
 
 | Command | Alias | Purpose | Description |
 |---|---|---|---|
@@ -30,6 +30,7 @@ The AI workflow operates on four standard commands (with shorthand aliases):
 | `spec:propose` | `scp` | Propose | Summarizes objectives, user stories, workflows, and open items without altering existing requirements. |
 | `spec:analyze` | `sca` | Analyze & Draft | Checks for conflicts against existing requirements, APIs, and DB schemas; drafts SRS, UML, OpenAPI, and DB schema. |
 | `spec:commit` | `scc` | Commit & Archive | Archives the user-verified version, assigns sequential ID, updates indexes, and generates a local Git commit. |
+| `spec:pdf` | `spd` | Export PDF | Exports a single `.md` file or an entire requirement folder (`REQ-001`) into a print-ready PDF specification. |
 
 Each finalized requirement produces a standardized, self-contained directory:
 
@@ -66,6 +67,20 @@ sa-spec defines what to build and its constraints; AI code tools build it right.
 - npm
 - Git
 
+### Cross-Platform Standalone Scripts (`.sh` / `.bat`)
+
+```bash
+# macOS / Linux
+./install.sh          # Install sa-spec
+./update.sh           # Update sa-spec to latest version
+./uninstall.sh        # Uninstall sa-spec
+
+# Windows (double-click or run via CMD / PowerShell)
+install.bat
+update.bat
+uninstall.bat
+```
+
 ### Global Installation via npm
 
 ```bash
@@ -88,6 +103,7 @@ sa-spec --version
 | `sa-spec init [--full] [--lang <lang>]` | Scaffolds the workspace skeleton (Supports `zh-TW`, `en`, `zh-CN`, `ja`, `ko`). |
 | `sa-spec new [--id REQ-001] --name login [--branch]` | Creates a requirement folder template. Omitting `--id` starts a draft in a feature branch (`feat/<name>`). |
 | `sa-spec finalize --name login` | Assigns the latest available sequential ID to a draft requirement, renames directory, substitutes `{{REQ_ID}}`, and regenerates index. |
+| `sa-spec pdf <target> [--split] [--output out.pdf]` | Converts a `.md` file or requirement (`REQ-001`) to a merged or split PDF (`--all` exports all). |
 | `sa-spec reindex` | Scans `project/REQ-*` directories and dynamically rebuilds `project/index.md` sorted by numerical ID. |
 | `sa-spec check` | Validates required project files and system spec status. |
 | `sa-spec status` | Displays overview status of requirements and specs. |
@@ -102,18 +118,18 @@ To solve sequential ID collisions and Git merge conflicts in team environments,
 
 ```mermaid
 flowchart TD
-    A["New Requirement: scp or sa-spec new --branch"] --> B["Create & switch to feat/cart branch<br/>Draft directory: project/cart/"]
+    A["New Requirement: scp or sa-spec new --branch"] --> B["Create & switch to feat/cart branch<br/>Push branch to remote if configured<br/>Draft directory: project/cart/"]
     B --> C["AI Analysis: sca<br/>Uses {{REQ_ID}} placeholder<br/>Pre-check against master spec baseline"]
     C --> D{"User Approved?<br/>Execute scc or finalize"}
-    D --> E["Auto query latest sequential ID N from master"]
-    E --> F["Auto assign project/REQ-N+1-cart/<br/>Replace {{REQ_ID}} and commit on feature branch"]
-    F --> G["Auto merge into master branch<br/>Dynamically rebuild project/index.md"]
+    D --> E["Push branch to remote & fetch first<br/>Then query latest ID N from master"]
+    E --> F["Auto assign project/REQ-N+1-cart/<br/>Replace {{REQ_ID}}, commit & push branch"]
+    F --> G["Auto merge into master & push to remote<br/>Dynamically rebuild project/index.md"]
     G --> H["Closed Loop: Zero conflicts, Continuous IDs!"]
 ```
 
-1. **Draft Phase (No ID Contention)**: Run `sa-spec new --name checkout --branch` or prompt `scp checkout` in AI chat. It creates `feat/checkout` and `project/checkout/` using `{{REQ_ID}}`. Parallel branches never collide. If an idea is abandoned, deleting the branch leaves zero ghost IDs.
+1. **Draft Phase (No ID Contention)**: Run `sa-spec new --name checkout --branch` or prompt `scp checkout` in AI chat. It creates `feat/checkout` (and automatically pushes it to Git remote if configured) and `project/checkout/` using `{{REQ_ID}}`. Parallel branches never collide. If an idea is abandoned, deleting the branch leaves zero ghost IDs.
 2. **Baseline Protection**: `spec:analyze` fetches latest `master` before analyzing to prevent missing newly merged API or table changes.
-3. **Late-Binding Finalize & Auto-Merge**: Running `scc` in AI chat (or `sa-spec finalize --name checkout`) automatically inspects master's latest ID, assigns `REQ-xxx`, replaces placeholders, commits, and **automatically merges into master** (`git checkout master && git merge feat/checkout`), then updates `project/index.md`.
+3. **Late-Binding Finalize, Auto-Merge & Remote Push**: Running `scc` in AI chat (or `sa-spec finalize --name checkout`) first pushes the feature branch to remote (if a remote exists) and syncs remote refs, then inspects master's latest ID, assigns `REQ-xxx`, replaces placeholders, commits, **automatically merges into master** (`git checkout master && git merge feat/checkout`), updates `project/index.md`, and pushes `master` to remote.
 4. **Conflict-Free Reindex**: `sa-spec reindex` builds `project/index.md` on the fly from disk.
 
 ---

package/README.ja.md

@@ -22,7 +22,7 @@
 
 OpenSpec、Claude Code、OpenAI Codex、Gemini CLI などの AI 開発ツールがコード実装を始める前に、要件のスコープ、境界線、データモデル、API 規約、権限マトリクス、受入条件を事前に明確化し、安全で堅牢な開発境界を定義します。
 
-AI ワークフローは 4 つの標準コマンド（エイリアス対応）で動作します：
+AI ワークフローは 5 つの標準コマンド（エイリアス対応）で動作します：
 
 | コマンド | エイリアス | 目的 | 説明 |
 |---|---|---|---|
@@ -30,6 +30,7 @@ AI ワークフローは 4 つの標準コマンド（エイリアス対応）
 | `spec:propose` | `scp` | 要件提案 | 既存の仕様を変更せず、目的・概要・初期フロー・確認事項を整理します。 |
 | `spec:analyze` | `sca` | 分析と起草 | 既存の要件、API、DB スキーマとの競合をチェックし、問題がなければ SRS、UML、OpenAPI、DB スキーマのドラフトを作成します。 |
 | `spec:commit` | `scc` | 確認と保存 | ユーザーが承認したバージョンを正式に採番・保存し、インデックスを更新して Git コミットを作成します。 |
+| `spec:pdf` | `spd` | PDF 出力 | 指定した `.md` ファイルまたは要件ディレクトリ（`REQ-001` など）を PDF 仕様書として出力します。 |
 
 各要件フォルダーには以下の標準成果物が生成されます：
 
@@ -66,6 +67,20 @@ sa-spec が仕様と境界を明確にし、AI 開発ツールが正しく実装
 - npm
 - Git
 
+### クロスプラットフォーム独立スクリプト (`.sh` / `.bat`)
+
+```bash
+# macOS / Linux
+./install.sh          # インストール
+./update.sh           # 最新版へアップデート
+./uninstall.sh        # アンインストール
+
+# Windows（ダブルクリック、または CMD / PowerShell で実行）
+install.bat
+update.bat
+uninstall.bat
+```
+
 ### グローバルインストール
 
 ```bash
@@ -88,6 +103,7 @@ sa-spec --version
 | `sa-spec init [--full] [--lang <lang>]` | ワークスペースの骨格を初期化します（`zh-TW`、`en`、`zh-CN`、`ja`、`ko` に対応）。 |
 | `sa-spec new [--id REQ-001] --name login [--branch]` | 要件テンプレートを作成します。`--id` を省略すると、Git 分岐を活用したドラフトモード（`feat/<name>`）で開始します。 |
 | `sa-spec finalize --name login` | ドラフト要件に最新の連続番号を割り当て、フォルダー名を変更し、`{{REQ_ID}}` を置換してインデックスを再生成します。 |
+| `sa-spec pdf <target> [--split] [--output out.pdf]` | 指定した `.md` または要件（`REQ-001`）を統合または個別 PDF として出力します（`--all` で全件出力）。 |
 | `sa-spec reindex` | `project/REQ-*` ディレクトリをスキャンし、数値順にソートされた `project/index.md` を自動再構築します。 |
 | `sa-spec check` | 必須ファイルとシステム仕様の状態を検証します。 |
 | `sa-spec status` | 要件とシステム仕様の概要ステータスを表示します。 |
@@ -102,18 +118,18 @@ sa-spec --version
 
 ```mermaid
 flowchart TD
-    A["要件提案: scp または sa-spec new --branch"] --> B["feat/cart ブランチを作成して切替<br/>ドラフトディレクトリ: project/cart/"]
+    A["要件提案: scp または sa-spec new --branch"] --> B["feat/cart ブランチを作成して切替<br/>remote があればブランチを自動 push<br/>ドラフトディレクトリ: project/cart/"]
     B --> C["AI による分析: sca<br/>内部で {{REQ_ID}} プレースホルダー使用<br/>master の最新仕様との競合予防チェック"]
     C --> D{"ユーザー承認?<br/>scc または finalize を実行"}
-    D --> E["master から最新の利用可能番号 N を自動取得"]
+    D --> E["先にブランチを remote へ push & fetch<br/>その後 master から最新番号 N を自動取得"]
     E --> F["project/REQ-N+1-cart/ に自動正式採番<br/>{{REQ_ID}} を置換してコミット"]
-    F --> G["master ブランチへ自動マージ<br/>project/index.md を動的に再生成"]
+    F --> G["master ブランチへ自動マージ＆remote へ push<br/>project/index.md を動的に再生成"]
     G --> H["自動閉ループ：競合ゼロ、連番維持！"]
 ```
 
-1. **ドラフト時は番号を奪い合わない**: `scp` または `sa-spec new --branch` でブランチを切り、`project/cart/` と `{{REQ_ID}}` を使って作業します。途中で要件を破棄する場合も、ブランチを削除するだけで済み、欠番（ゴーストID）を残しません。
+1. **ドラフト時は番号を奪い合わない**: `scp` または `sa-spec new --branch` でブランチを切り（Git remote が設定されていれば自動的に remote へ push）、`project/cart/` と `{{REQ_ID}}` を使って作業します。途中で要件を破棄する場合も、ブランチを削除するだけで済み、欠番（ゴーストID）を残しません。
 2. **基線同期で競合見落としを防止**: `spec:analyze` の実行前に master の最新状態を取得し、他メンバーがマージした最新の API やテーブル変更を反映して競合チェックを行います。
-3. **自動採番と主ブランチへの自動マージ**: `scc` または `sa-spec finalize` を実行すると、**master から次の番号を自動取得して採番・置換・コミット**し、**master ブランチへ自動切り替え＆自動マージ**を行い、`project/index.md` を最新状態に再生成します。
+3. **先行 push・自動採番・主ブランチ自動マージ**: `scc` または `sa-spec finalize` を実行すると、remote が存在する場合は**まずブランチを remote に push して同期**した後、**master から次の番号を自動取得して採番・置換・コミット**し、**master ブランチへ自動切り替え＆自動マージ・`project/index.md` 再生成・remote への自動 push** までを一気通貫で行います。
 4. **インデックスのコンフリクト解消**: `sa-spec reindex` でディレクトリから常に決定論的に `project/index.md` を再構築します。
 
 ---

package/README.ko.md

@@ -22,7 +22,7 @@
 
 OpenSpec, Claude Code, OpenAI Codex, Gemini CLI 등 코드 생성 AI 도구가 구현을 시작하기 전에, 요구사항의 범위, 경계, 데이터 모델, API 인터페이스, 권한 매트릭스, 인수 조건을 사전에 명확히 정의하여 후속 개발이 안전하고 명확한 경계 내에서 진행되도록 보장합니다.
 
-AI 워크플로는 4가지 표준 명령어(별칭 지원)를 기반으로 동작합니다:
+AI 워크플로는 5가지 표준 명령어(별칭 지원)를 기반으로 동작합니다:
 
 | 표준 명령어 | 별칭 | 단계 | 설명 |
 |---|---|---|---|
@@ -30,6 +30,7 @@ AI 워크플로는 4가지 표준 명령어(별칭 지원)를 기반으로 동
 | `spec:propose` | `scp` | 요구사항 제안 | 기존 사양을 변경하지 않고 목표, 요약, 초기 흐름 및 미확인 사항을 정리합니다. |
 | `spec:analyze` | `sca` | 분석 및 초안 작성 | 기존 요구사항, API, DB와의 충돌 여부를 검사하고, 문제가 없을 때만 SRS, UML, OpenAPI, DB Schema 초안을 작성합니다. |
 | `spec:commit` | `scc` | 확인 및 보관 | 사용자가 승인한 버전을 정식 번호로 보관하고, 인덱스를 갱신하며 로컬 Git 커밋을 생성합니다. |
+| `spec:pdf` | `spd` | PDF 내보내기 | 지정한 `.md` 파일이나 요구사항 폴더(`REQ-001` 등)를 PDF 사양서로 변환합니다. |
 
 보관된 각 요구사항은 독립적이고 완전한 폴더로 구성됩니다:
 
@@ -66,6 +67,20 @@ sa-spec이 요구사항과 경계를 명확히 정의하고, AI 개발 도구가
 - npm
 - Git
 
+### 크로스 플랫폼 독립 스크립트 (`.sh` / `.bat`)
+
+```bash
+# macOS / Linux
+./install.sh          # 설치 (install)
+./update.sh           # 최신 버전 업데이트 (update)
+./uninstall.sh        # 제거 (uninstall)
+
+# Windows (더블클릭 또는 CMD / PowerShell 실행)
+install.bat
+update.bat
+uninstall.bat
+```
+
 ### npm 글로벌 설치
 
 ```bash
@@ -88,6 +103,7 @@ sa-spec --version
 | `sa-spec init [--full] [--lang <lang>]` | 워크스페이스 골격을 생성합니다 (`zh-TW`, `en`, `zh-CN`, `ja`, `ko` 지원, 기본값 `zh-TW`). |
 | `sa-spec new [--id REQ-001] --name login [--branch]` | 요구사항 템플릿 폴더를 생성합니다. `--id` 생략 시 다중 사용자 초안 브랜치(`feat/<name>`)로 생성됩니다. |
 | `sa-spec finalize --name login` | 초안 요구사항에 최신 연속 번호를 할당하고 폴더명 변경, `{{REQ_ID}}` 치환 및 인덱스를 자동 재구축합니다. |
+| `sa-spec pdf <target> [--split] [--output out.pdf]` | 지정한 `.md` 파일 또는 요구사항(`REQ-001`)을 통합 또는 개별 PDF로 변환합니다 (`--all` 전체 내보내기). |
 | `sa-spec reindex` | `project/REQ-*` 디렉토리를 스캔하여 번호순으로 정렬된 `project/index.md`를 동적으로 재생성합니다. |
 | `sa-spec check` | 필수 파일과 시스템 사양 상태를 검증합니다. |
 | `sa-spec status` | 요구사항 및 시스템 사양 현황을 확인합니다. |
@@ -102,18 +118,18 @@ sa-spec --version
 
 ```mermaid
 flowchart TD
-    A["요구사항 제안: scp 또는 sa-spec new --branch"] --> B["feat/cart 브랜치 생성 및 전환<br/>초안 디렉토리: project/cart/"]
+    A["요구사항 제안: scp 또는 sa-spec new --branch"] --> B["feat/cart 브랜치 생성 및 전환<br/>remote가 있으면 브랜치 자동 push<br/>초안 디렉토리: project/cart/"]
     B --> C["AI 분석 및 초안: sca<br/>내부에서 {{REQ_ID}} 플레이스홀더 사용<br/>master 최신 사양 기반 충돌 검사"]
     C --> D{"사용자 승인 완료?<br/>scc 또는 finalize 실행"}
-    D --> E["master에서 최신 사용 가능 번호 N 자동 확인"]
+    D --> E["먼저 브랜치를 remote에 push 및 fetch 동기화<br/>그 후 master에서 최신 번호 N 자동 확인"]
     E --> F["project/REQ-N+1-cart/ 자동 채번 및 커밋<br/>{{REQ_ID}}를 공식 번호로 일괄 치환"]
-    F --> G["master 브랜치로 자동 머지<br/>project/index.md 동적 재생성"]
+    F --> G["master 브랜치로 자동 머지 및 remote push<br/>project/index.md 동적 재생성"]
     G --> H["자동 루프 완성: 충돌 제로, 연속된 번호 유지!"]
 ```
 
-1. **초안 단계 번호 미선점**: `scp` 또는 `sa-spec new --branch` 명령으로 독립 브랜치를 생성하고 `project/cart/`와 `{{REQ_ID}}` 플레이스홀더를 사용합니다. 요구사항이 중도 폐기되어도 브랜치만 삭제하면 되며, 결번(고스트 번호)이 발생하지 않습니다.
+1. **초안 단계 번호 미선점**: `scp` 또는 `sa-spec new --branch` 명령으로 독립 브랜치를 생성하고(Git remote가 설정되어 있으면 자동으로 remote에 push) `project/cart/`와 `{{REQ_ID}}` 플레이스홀더를 사용합니다. 요구사항이 중도 폐기되어도 브랜치만 삭제하면 되며, 결번(고스트 번호)이 발생하지 않습니다.
 2. **사양 기준선 동기화**: `spec:analyze` 실행 전 master의 최신 상태를 동기화하여 다른 팀원이 머지한 API나 테이블과의 충돌 누락을 방지합니다.
-3. **자동 신규 번호 채번 및 메인 브랜치 자동 머지**: `scc` 또는 `sa-spec finalize` 실행 시 **master에서 다음 번호를 자동 조회하여 채번·치환·커밋**하고, **master 브랜치로 자동 전환 후 자동 머지**를 수행하며 `project/index.md`를 최신 상태로 정렬 재생성합니다.
+3. **선행 push, 자동 신규 번호 채번 및 메인 브랜치 자동 머지**: `scc` 또는 `sa-spec finalize` 실행 시 remote가 있으면 **먼저 현재 브랜치를 remote에 push하고 최신 상태를 동기화**한 뒤, **master에서 다음 번호를 자동 조회하여 채번·치환·커밋**하고, **master 브랜치로 자동 전환 후 자동 머지 및 remote push**를 수행하며 `project/index.md`를 최신 상태로 정렬 재생성합니다.
 4. **인덱스 머지 충돌 제거**: `sa-spec reindex` 명령으로 디렉토리 상태에서 `project/index.md`를 언제든 완벽하게 재생성합니다.
 
 ---

package/README.zh-CN.md

@@ -22,7 +22,7 @@
 
 在 OpenSpec、Claude Code、OpenAI Codex、Gemini CLI 等代码生成工具介入之前，`sa-spec` 先行厘清需求边界、业务规则、数据模型、API 契约、权限矩阵与验收条件，避免 AI 编码时随心所欲破坏系统架构。
 
-AI 工作流使用四个标准指令（支持简写别名）：
+AI 工作流使用五个标准指令（支持简写别名）：
 
 | 标准指令 | 简写 | 阶段 | 说明 |
 |---|---|---|---|
@@ -30,6 +30,7 @@ AI 工作流使用四个标准指令（支持简写别名）：
 | `spec:propose` | `scp` | 提出需求 | 整理需求摘要、目标、初步流程与待确认事项，不修改已有规格。 |
 | `spec:analyze` | `sca` | 分析与起草 | 检查新需求是否与既有需求、API、DB 发生冲突；无冲突才产出 SRS、UML、OpenAPI 与 DB Schema 草案。 |
 | `spec:commit` | `scc` | 确认归档 | 用户确认后正式定号归档，更新索引与系统总表，并自动创建本地 Git commit。 |
+| `spec:pdf` | `spd` | 导出 PDF | 将指定的 `.md` 文件或需求目录（如 `REQ-001`）一键导出为 PDF 规格说明书。 |
 
 每个归档的需求固定包含一个独立完整的文件夹：
 
@@ -66,6 +67,20 @@ sa-spec 先把需求说清楚、定好边界；AI 代码工具再把需求实现
 - npm
 - Git
 
+### 跨平台独立脚本 (`.sh` / `.bat`)
+
+```bash
+# macOS / Linux
+./install.sh          # 安装 sa-spec
+./update.sh           # 更新 sa-spec 至最新版本
+./uninstall.sh        # 卸载 sa-spec
+
+# Windows（直接双击或在 CMD / PowerShell 执行）
+install.bat
+update.bat
+uninstall.bat
+```
+
 ### 全局安装
 
 ```bash
@@ -88,6 +103,7 @@ sa-spec --version
 | `sa-spec init [--full] [--lang <lang>]` | 初始化工作台骨架（支持 `zh-TW`、`en`、`zh-CN`、`ja`、`ko`，默认 `zh-TW`）。 |
 | `sa-spec new [--id REQ-001] --name login [--branch]` | 创建需求模板文件夹。省略 `--id` 时自动切入多人协作草稿分支（`feat/<name>`）。 |
 | `sa-spec finalize --name login` | 将草稿需求正式定号归档为最新序号，自动重命名目录、替换 `{{REQ_ID}}` 并重构索引。 |
+| `sa-spec pdf <target> [--split] [--output out.pdf]` | 将指定 `.md` 或需求（如 `REQ-001`）合并或拆分导出为 PDF（`--all` 导出全项目）。 |
 | `sa-spec reindex` | 扫描 `project/REQ-*` 目录，按序数字顺序动态重新生成 `project/index.md`。 |
 | `sa-spec check` | 检查项目必要文件与规格完整性。 |
 | `sa-spec status` | 查看系统规格与需求总览状态。 |
@@ -102,18 +118,18 @@ sa-spec --version
 
 ```mermaid
 flowchart TD
-    A["提出需求: scp 或 sa-spec new --branch"] --> B["建立并切换至 feat/cart 分支<br/>创建草稿目录 project/cart/"]
+    A["提出需求: scp 或 sa-spec new --branch"] --> B["建立并切换至 feat/cart 分支<br/>若有 remote 自动推分支至远端<br/>创建草稿目录 project/cart/"]
     B --> C["AI 分析与起草: sca<br/>内部使用 {{REQ_ID}} 占位<br/>自动同步 master 最新规格防冲突"]
     C --> D{"用户确认通过<br/>执行 scc 或 finalize"}
-    D --> E["自动向主分支查询最新可用序号 N"]
+    D --> E["先推分支至 remote 并同步远端状态<br/>再向主分支查询最新可用序号 N"]
     E --> F["自动定号为 project/REQ-N+1-cart/<br/>批量替换 {{REQ_ID}} 并建立提交"]
-    F --> G["自动合并至 master 主分支<br/>动态重新生成 project/index.md"]
+    F --> G["自动合并至 master 主分支并推上 remote<br/>动态重新生成 project/index.md"]
     G --> H["完成闭环：零冲突、序号永远连续！"]
 ```
 
-1. **草稿不抢号**：在分支开发时使用 `scp` 或 `sa-spec new --branch`，建立 `project/cart/` 与 `{{REQ_ID}}` 占位符。多人同时提出需求互不冲突。如果需求放弃，直接删除分支，**绝不遗留幽灵跳号**。
+1. **草稿不抢号（自动推分支）**：在分支开发时使用 `scp` 或 `sa-spec new --branch`，建立 `feat/cart`（若配置了 Git remote 则自动推送分支至远端）以及 `project/cart/` 与 `{{REQ_ID}}` 占位符。多人同时提出需求互不冲突。如果需求放弃，直接删除分支，**绝不遗留幽灵跳号**。
 2. **基线同步防漏检**：执行 `spec:analyze` 前先确认同步远端 master 规格，确保以全系统最新状态进行冲突检查。
-3. **自动拿新号与自动合并**：执行 `scc`（或 `sa-spec finalize --name cart`）时，系统**自动向 master 申请下一个新号定号**、批量替换占位符、完成提交，并**自动切换回 master 并合并该 feature 分支**，随后自动重建 `project/index.md`。
+3. **先推分支、自动拿新号与自动合并推送**：执行 `scc`（或 `sa-spec finalize --name cart`）时，若有 remote 会**先将当前分支推送至 remote 并同步远端**，再**自动向 master 申请下一个新号定号**、批量替换占位符、完成提交，并**自动切换回 master 合并该 feature 分支、重建 `project/index.md` 后推送至 remote**。
 4. **动态重建索引**：`sa-spec reindex` 随时可由目录动态排序生成总表，消除 `index.md` 的 merge conflict。
 
 ---

package/README.zh-TW.md

@@ -32,6 +32,7 @@ sa-spec init --full
 - `spec:propose` (`scp`) $\to$ **AI 自動建立 feature 分支與草稿目錄**（零手動指令）
 - `spec:analyze` (`sca`) $\to$ AI 衝突檢查並產出規格文件草稿
 - `spec:commit` (`scc`) $\to$ **AI 自動向主分支領取新號並自動合併回主分支！**
+- `spec:pdf` (`spd`) $\to$ **一鍵將單一 `.md` 或整個需求規格書轉為高品質 PDF！**
 
 👉 **Language Guides: [English](./README.en.md) | [繁體中文](./README.zh-TW.md) | [简体中文](./README.zh-CN.md) | [日本語](./README.ja.md) | [한국어](./README.ko.md)**
 
@@ -39,7 +40,7 @@ sa-spec init --full
 
 `sa-spec` 是一個輕量的系統分析文件工作台，用固定流程把需求想法整理成可確認、可歸檔、可檢查的文件。
 
-AI 工作流只使用四個指令，並支援簡寫別名（兩者等價）：
+AI 工作流使用五個指令，並支援簡寫別名（兩者等價）：
 
 | 標準指令 | 簡寫 | 說明 |
 |---|---|---|
@@ -47,6 +48,7 @@ AI 工作流只使用四個指令，並支援簡寫別名（兩者等價）：
 | `spec:propose` | `scp` | 提出需求並整理摘要 |
 | `spec:analyze` | `sca` | 衝突檢查與規格起草 |
 | `spec:commit` | `scc` | 確認歸檔並建立 Git commit |
+| `spec:pdf` | `spd` | 將指定 `.md` 或需求目錄匯出為 PDF |
 
 每個需求歸檔後固定包含：
 
@@ -96,6 +98,25 @@ npm --version
 git --version
 ```
 
+## 一鍵腳本管理（安裝 / 更新 / 解除安裝）
+
+專案內建獨立的跨平台腳本，直接執行對應檔案即可完成安裝、更新或解除安裝：
+
+### macOS / Linux (`.sh`)
+```bash
+./install.sh      # 安裝 sa-spec
+./update.sh       # 更新 sa-spec 至最新版本
+./uninstall.sh    # 解除安裝 sa-spec
+```
+
+### Windows (`.bat`)
+可直接雙擊執行，或在 CMD / PowerShell 輸入：
+```bat
+install.bat       &:: 安裝 sa-spec
+update.bat        &:: 更新 sa-spec 至最新版本
+uninstall.bat     &:: 解除安裝 sa-spec
+```
+
 ## macOS 安裝
 
 使用 npm 安裝：
@@ -275,6 +296,7 @@ sa-spec init --full
 | `sa-spec init [--full] [--lang zh-TW|en|zh-CN|ja|ko]` | 建立文件骨架與規則文件（支援 5 種語言，預設 `zh-TW`）。 |
 | `sa-spec new [--id REQ-001] --name login [--branch]` | 建立需求資料夾與空白文件模板（未帶 `--id` 時啟用多人草稿模式，可選 `--branch` 自動建立並切換至 `feat/<name>` 分支）。 |
 | `sa-spec finalize --name login` | 將草稿需求定號歸檔為最新序號（自動計算最新號碼、重命名目錄、批次置換 `{{REQ_ID}}` 並重建索引）。 |
+| `sa-spec pdf <target> [--split] [--output out.pdf]` | 將指定 `.md` 轉為同名 `.pdf`，或將需求編號/目錄（如 `REQ-001`）整包合併匯出成一份完整規格書 PDF（加 `--split` 則各檔獨立轉出，`--all` 匯出全專案）。 |
 | `sa-spec reindex` | 掃描 `project/REQ-*` 目錄，依序號重新生成乾淨無衝突的 `project/index.md`。 |
 | `sa-spec check` | 檢查基本文件是否存在。 |
 | `sa-spec status` | 顯示系統規格與需求索引狀態。 |
@@ -324,6 +346,7 @@ Markdown、PlantUML、YAML、GitLens 這類套件可以提升閱讀與檢查體
 | AI 工作流程 | `spec:propose` / `scp` | VS Code AI 對話側邊欄 | 整理使用者提出的需求。 |
 | AI 工作流程 | `spec:analyze` / `sca` | VS Code AI 對話側邊欄 | 檢查衝突並產出待確認草稿。 |
 | AI 工作流程 | `spec:commit` / `scc` | VS Code AI 對話側邊欄 | 歸檔已確認版本並建立本機 Git commit。 |
+| AI 工作流程 | `spec:pdf` / `spd` | VS Code AI 對話側邊欄 | 將指定 `.md` 或需求目錄匯出為 PDF 規格書。 |
 
 建議操作順序：
 
@@ -353,6 +376,7 @@ spec:commit  # 或簡寫 scc
 | `spec:propose` | `scp` | 使用者提出需求後，整理需求摘要、目標、初步流程與待確認事項。 |
 | `spec:analyze` | `sca` | 檢查是否與既有需求衝突；無衝突才產出 SRS、UML、OpenAPI、DB Schema 草稿。 |
 | `spec:commit` | `scc` | 使用者確認無衝突版本後，將版本歸檔到 `project/`，並建立本機 Git commit。 |
+| `spec:pdf` | `spd` | 將指定的 `.md` 檔或需求（如 `REQ-001`）匯出為高品質 PDF。 |
 
 狀態機：
 
@@ -385,7 +409,7 @@ commit (scc) -> 歸檔 -> 本機 Git commit
 docs(REQ-001): 番茄時鐘 - 新增專注與休息計時需求
 ```
 
-只有在使用者明確要求推送 remote，或專案設定啟用 auto-push 時，才會執行 `git push`。如果 push 失敗，只回報認證或網路問題，不會回滾已完成的文件歸檔與本機 commit。
+**鐵律**：只要 Git repository 有設定 remote（例如 `origin`），在 `scp` 建立分支與 `scc` 歸檔合併時，都會**自動執行 `git push` 推送至 remote**。如果 push 失敗，只回報認證或網路問題，不會回滾已完成的文件歸檔與本機 commit。
 
 ## 多人協作解決方案（Git-Flow 與延遲綁定 ID）
 
@@ -397,12 +421,12 @@ docs(REQ-001): 番茄時鐘 - 新增專注與休息計時需求
 
 ```mermaid
 flowchart TD
-    A["開新需求: scp 或 sa-spec new --branch"] --> B["建立並切換至 feat/cart 分支<br/>以 project/cart/ 建立草稿目錄"]
+    A["開新需求: scp 或 sa-spec new --branch"] --> B["建立並切換至 feat/cart 分支<br/>若有 remote 自動推分支至遠端<br/>以 project/cart/ 建立草稿目錄"]
     B --> C["AI 分析與起草: sca<br/>內部使用 {{REQ_ID}} 佔位<br/>自動同步 master 規格防護"]
     C --> D{"使用者確認通過<br/>執行 scc 或 finalize"}
-    D --> E["自動查詢主分支最新序號 N"]
+    D --> E["先推分支至 remote 並同步遠端狀態<br/>再查詢主分支最新序號 N"]
     E --> F["自動定號為 project/REQ-N+1-cart/<br/>批次置換 {{REQ_ID}} 並建立 commit"]
-    F --> G["自動合併至 master 主分支<br/>動態重新生成 project/index.md"]
+    F --> G["自動合併至 master 主分支並推上 remote<br/>動態重新生成 project/index.md"]
     G --> H["完成閉環：零衝突、序號永遠連續！"]
 ```
 
@@ -415,7 +439,7 @@ flowchart TD
   ```text
   scp 購物車結帳需求
   ```
-  AI 收到後，會**自動在背景執行 `git checkout -b feat/cart-checkout` 建立並切換分支**，並在 `project/cart-checkout/` 建立草稿目錄！
+  AI 收到後，會**自動在背景執行 `git checkout -b feat/cart-checkout` 建立並切換分支**，檢查若有設定 Git remote 則自動將分支推上遠端（`git push -u origin feat/cart-checkout`），並在 `project/cart-checkout/` 建立草稿目錄！
 * **方式 B（CLI 終端指令）**：
   ```bash
   sa-spec new --name cart-checkout --branch
@@ -425,7 +449,7 @@ flowchart TD
 #### 2. 分析與衝突檢查（規格基線同步）
 在分支上執行 `spec:analyze`（或 `sca`）前，工具會確認已取得 `master`（或 `origin/master`）的最新規格，確保是以全專案最新基準進行影響評估，避免因分支落後而漏檢權限、API 或資料表衝突。
 
-#### 3. 確認歸檔與延遲定號（自動領號 + 自動合併回主分支）
+#### 3. 確認歸檔與延遲定號（先推分支 + 自動領號 + 自動合併並推上 Remote）
 當需求規格經使用者確認無誤，準備歸檔時：
 
 * **方式 A（純 AI 自動化，最推薦）**：在 AI 側邊欄直接輸入：
@@ -433,15 +457,16 @@ flowchart TD
   scc
   ```
   AI 收到後會自動完成全自動 Git-Flow 閉環作業：
-  1. **自動向主分支查詢並取得新號**：查詢 master/main 目前最大序號（例如最大是 `REQ-005`，自動領取最新號 `REQ-006`），避免號碼競爭。
-  2. **自動定名更名**：使用 `git mv` 將目錄重命名為 `project/REQ-006-cart-checkout`，並將目錄內所有檔案的 `{{REQ_ID}}` 批次置換為 `REQ-006`。
-  3. **自動建立本機提交**：在 feature 分支自動建立 commit `docs(REQ-006): cart-checkout - 規格確認歸檔`。
-  4. **自動合併至主分支**：自動切換至主分支（`git checkout master`），將 feature 分支自動合併回主分支（`git merge feat/cart-checkout`），並重新生成主分支的 `project/index.md`，保證主分支規格最新且永遠不衝突！
+  1. **先推分支至 Remote 並同步遠端**：若 Git 有設定 remote，先將目前分支推送至遠端並執行 `git fetch` 同步最新狀態。
+  2. **自動向主分支查詢並取得新號**：查詢 master/main（含遠端主分支）目前最大序號（例如最大是 `REQ-005`，自動領取最新號 `REQ-006`），避免號碼競爭。
+  3. **自動定名更名**：使用 `git mv` 將目錄重命名為 `project/REQ-006-cart-checkout`，並將目錄內所有檔案的 `{{REQ_ID}}` 批次置換為 `REQ-006`。
+  4. **自動建立提交並推送分支**：在 feature 分支自動建立 commit `docs(REQ-006): cart-checkout - 規格確認歸檔`，若有 remote 則同步推送至遠端。
+  5. **自動合併至主分支並推送至 Remote**：自動切換至主分支（`git checkout master`），將 feature 分支自動合併回主分支（`git merge feat/cart-checkout`），重新生成主分支的 `project/index.md`，若有 remote 則自動將主分支推送至遠端（`git push origin master`），保證主分支規格最新且永遠不衝突！
 * **方式 B（CLI 終端指令）**：
   ```bash
   sa-spec finalize --name cart-checkout
   ```
-  CLI 同樣會自動查詢主分支最新序號定號、置換佔位符、完成提交並自動合併回 master！若想保留在當前分支手動處理，可加上 `--no-merge` 參數。
+  CLI 同樣會先推分支至 remote、查詢主分支最新序號定號、置換佔位符、完成提交、自動合併回 master 並推送至 remote！若想保留在當前分支手動處理，可加上 `--no-merge` 參數。
 
 #### 4. 消除索引合併衝突（`sa-spec reindex`）
 `project/index.md` 改為由目錄動態生成的「衍生清單」，不再依賴脆弱的手動 append：
@@ -702,7 +727,7 @@ git status
 git log -1 --oneline
 ```
 
-若要推送到 remote，需要明確要求 AI 執行 push，或自行執行：
+若 Git 有設定 remote，AI 與 CLI 會在建立分支與歸檔合併時自動執行 `git push` 推送至遠端；若當時尚未設定 remote，事後也可手動執行：
 
 ```bash
 git push origin main
@@ -719,11 +744,21 @@ git push origin master
 - 未經使用者確認，不得標示為 `已審核`。
 - `spec:analyze` 發現衝突時不得產出最終文件，也不得修改既有需求文件。
 - `project/system-spec.md` 只能在 `spec:commit` 依使用者確認內容更新。
-- `spec:commit` 會自動建立本機 Git commit；remote push 需使用者明確要求或啟用 auto-push。
+- **鐵律**：只要 Git 有設定 remote，`scp` 與 `scc` 都會自動將分支與主分支推送至 remote。
 - 一次最多問 3 個待確認問題，優先詢問會影響範圍、資料、權限、API、DB 或驗收的問題。
 
 ## 更新紀錄
 
+### v0.2.7
+- **新增 Markdown 轉 PDF 指令（`spec:pdf` / `spd` / `sa-spec pdf`）與跨平台獨立安裝腳本**：
+  - **Markdown 轉 PDF 支援**：新增 AI 指令 `spec:pdf`（簡寫 `spd`）與 CLI 指令 `sa-spec pdf <target> [--split] [--output out.pdf]`（及 `--all`），支援單一 `.md` 轉換、需求目錄整包合併匯出成一份完整規格書 PDF，或加 `--split` 各檔獨立匯出。
+  - **跨平台獨立管理腳本**：新增 macOS / Linux（`install.sh`、`update.sh`、`uninstall.sh`）與 Windows（`install.bat`、`update.bat`、`uninstall.bat`）6 個獨立執行腳本，一鍵完成安裝、更新與解除安裝。
+
+### v0.2.6
+- **Git Remote 自動推送鐵律（Remote Auto-Push）**：
+  - **`scp` 建立分支自動推上遠端**：執行 `spec:propose`（`scp`）或 `sa-spec new --branch` 建立 feature 分支後，自動偵測是否有設定 Git remote；若有則立即將新分支推送至遠端（`git push -u <remote> feat/<name>`）。
+  - **`scc` 先推分支再領號與主分支自動推送**：執行 `spec:commit`（`scc`）或 `sa-spec finalize` 時，若有設定 Git remote，會**先將目前分支推送至 remote 並同步遠端狀態**，接著才查詢主分支（`master`/`main`）最新可用序號定號，完成 feature 分支提交與推送、自動合併回主分支後，**自動將主分支推送至 remote**。
+
 ### v0.2.5
 - **支援前端 UI 線框圖（PlantUML Salt Code-as-Wireframe）**：
   - **純文字代碼化線框圖**：在 `uml/` 目錄新增標準 `uml/wireframe.puml`，使用 PlantUML Salt 語法（`@startsalt ... @endsalt`）以純文字定義頁面排版、輸入欄位、選項與按鈕，可直接在 VS Code 渲染預覽，並可納入 Git 版本追蹤。

package/install.bat

@@ -0,0 +1,43 @@
+@echo off
+setlocal EnableDelayedExpansion
+chcp 65001 >nul 2>&1
+
+set "PACKAGE_NAME=@loviusc/sa-spec"
+set "SCRIPT_DIR=%~dp0"
+
+echo [sa-spec] 開始安裝 (Windows)...
+
+where node >nul 2>&1
+if %errorlevel% neq 0 (
+    echo [錯誤] 未偵測到 Node.js，請先安裝 Node.js 18 或以上版本: https://nodejs.org/
+    pause
+    exit /b 1
+)
+
+where npm >nul 2>&1
+if %errorlevel% neq 0 (
+    echo [錯誤] 未偵測到 npm，請確認 Node.js 安裝是否完整。
+    pause
+    exit /b 1
+)
+
+set "IS_SOURCE=0"
+if exist "%SCRIPT_DIR%package.json" (
+    findstr /C:"@loviusc/sa-spec" "%SCRIPT_DIR%package.json" >nul 2>&1
+    if !errorlevel! equ 0 set "IS_SOURCE=1"
+)
+
+if "%IS_SOURCE%"=="1" (
+    echo [安裝] 偵測到 sa-spec 原始碼目錄，執行 npm install 與 npm link...
+    pushd "%SCRIPT_DIR%"
+    call npm install
+    call npm link
+    popd
+) else (
+    echo [安裝] 從 npm 全域安裝 %PACKAGE_NAME%...
+    call npm install -g %PACKAGE_NAME%
+)
+
+echo [完成] sa-spec 安裝完成！
+call sa-spec --version 2>nul
+pause

package/install.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+set -e
+
+PACKAGE_NAME="@loviusc/sa-spec"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+echo "[sa-spec] 開始安裝 (${OSTYPE:-macOS/Linux})..."
+
+if ! command -v node >/dev/null 2>&1; then
+  echo "[錯誤] 未偵測到 Node.js，請先安裝 Node.js 18 或以上版本: https://nodejs.org/"
+  exit 1
+fi
+
+if ! command -v npm >/dev/null 2>&1; then
+  echo "[錯誤] 未偵測到 npm，請確認 Node.js 與 npm 是否安裝完整。"
+  exit 1
+fi
+
+# 若全域目錄無寫入權限，自動切換至 ~/.npm-global 避免 sudo 權限問題
+NPM_PREFIX="$(npm prefix -g 2>/dev/null || echo "")"
+if [ -n "${NPM_PREFIX}" ] && [ ! -w "${NPM_PREFIX}" ] && [ ! -w "${NPM_PREFIX}/lib" ]; then
+  echo "[權限設定] 偵測到全域目錄 (${NPM_PREFIX}) 無寫入權限，自動設定 ~/.npm-global..."
+  mkdir -p "${HOME}/.npm-global"
+  npm config set prefix "${HOME}/.npm-global"
+  export PATH="${HOME}/.npm-global/bin:${PATH}"
+  for rc in "${HOME}/.zshrc" "${HOME}/.bashrc"; do
+    if [ -f "${rc}" ] && ! grep -q '.npm-global/bin' "${rc}" 2>/dev/null; then
+      echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> "${rc}"
+    fi
+  done
+fi
+
+if [ -f "${SCRIPT_DIR}/package.json" ] && grep -q '"@loviusc/sa-spec"' "${SCRIPT_DIR}/package.json" 2>/dev/null; then
+  echo "[安裝] 偵測到 sa-spec 原始碼目錄，執行 npm install 與 npm link..."
+  cd "${SCRIPT_DIR}"
+  npm install
+  npm link
+else
+  echo "[安裝] 從 npm 全域安裝 ${PACKAGE_NAME}..."
+  npm install -g "${PACKAGE_NAME}"
+fi
+
+echo "[完成] sa-spec 安裝成功！目前版本: $(sa-spec --version 2>/dev/null || echo '請重開終端機以套用 PATH')"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loviusc/sa-spec",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "Personal system analysis documentation workspace CLI",
   "publishConfig": {
     "access": "public",
@@ -21,11 +21,17 @@
     "bin/",
     "src/",
     "templates/",
+    "install.sh",
+    "update.sh",
+    "uninstall.sh",
+    "install.bat",
+    "update.bat",
+    "uninstall.bat",
     "readme.md",
     "README*.md"
   ],
   "scripts": {
-    "check": "node --check src/cli.js && node --check bin/sa-spec.js"
+    "check": "node --check src/cli.js && node --check src/pdf.js && node --check bin/sa-spec.js"
   },
   "keywords": [
     "system-analysis",