docs: rewrite README with Mermaid pipeline diagram, troubleshooting, and roadmap

Rlin1027 · claude · Rlin1027 · commit 697d22cc0e11 · 2026-02-24T15:25:17.000+08:00
Replace ASCII art flow chart with Mermaid graph LR for native GitHub
rendering. Add Requirements, Troubleshooting, Project Structure, and
Roadmap sections. Update CHANGELOG with R-12 and README rewrite entries.

Co-Authored-By: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -16,12 +16,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Confidence scoring in CLI output
 - Pre-migration confirmation prompt (`--yes` to skip)
 - Bridge/fallback guidance for untranslatable packages
+- CI/CD integration templates for GitHub Actions and GitLab CI (`ci-templates/`)
+- GitHub Actions CI pipeline (lint, type-check, test on Python 3.10–3.13)
+- Automated PyPI release via GitHub Release + trusted publishing
+- README rewrite with pipeline diagram, prerequisites, troubleshooting, and roadmap
 
 ### Changed
 - Updated CLI help text for analyze and status commands
 - Improved launch rule conversion for `<machine>` and `<test>` tags
 - Updated PromptBuilder to support custom rule merging
 
+### Fixed
+- Release workflow missing `environment: pypi` for PyPI trusted publishing
+
 ## [0.1.0] - 2026-02-24
 
 ### Added
diff --git a/README.md b/README.md
@@ -2,11 +2,13 @@
 
 **AI-driven ROS1 to ROS2 migration CLI tool.**
 
-[![CI](https://img.shields.io/github/actions/workflow/status/Rlin1027/ROSForge/ci.yml?branch=main&label=CI)](https://github.com/Rlin1027/ROSForge/actions) [![PyPI](https://img.shields.io/pypi/v/rosforge)](https://pypi.org/project/rosforge/) [![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
+[![CI](https://img.shields.io/github/actions/workflow/status/Rlin1027/ROSForge/ci.yml?branch=main&label=CI)](https://github.com/Rlin1027/ROSForge/actions) [![PyPI](https://img.shields.io/pypi/v/rosforge)](https://pypi.org/project/rosforge/) [![Python](https://img.shields.io/pypi/pyversions/rosforge)](https://pypi.org/project/rosforge/) [![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
 
 ## Why ROSForge?
 
-ROS1 reached end-of-life in May 2025. Migrating a production codebase to ROS2 by hand is tedious and error-prone: API namespaces changed, CMakeLists.txt rules are different, launch files moved to Python, and hundreds of `ros::` calls need one-by-one replacement. ROSForge automates this work by combining a static knowledge base of known API mappings with an AI backend that handles the cases rules alone cannot cover. The result is a complete, confidence-scored migration in minutes rather than days.
+ROS1 reached end-of-life in May 2025. Migrating a production codebase to ROS2 by hand is tedious and error-prone: API namespaces changed, CMakeLists.txt rules are different, launch files moved from XML to Python, and hundreds of `ros::` calls need one-by-one replacement.
+
+ROSForge automates this work by combining a **static knowledge base** of known API mappings with an **AI backend** that handles the cases rules alone cannot cover. The result is a complete, confidence-scored migration in minutes rather than days.
 
 ## Features
 
@@ -19,45 +21,110 @@ ROS1 reached end-of-life in May 2025. Migrating a production codebase to ROS2 by
 - **Static knowledge base** — built-in C++/Python API mappings, CMake rules, and launch conversion patterns
 - **Cost estimation** — token and USD estimates shown before any API calls are made
 - **Confidence scoring** — every output file is rated HIGH / MEDIUM / LOW; low-confidence files are flagged for manual review
+- **CI/CD templates** — ready-made GitHub Actions and GitLab CI integration
+
+## Requirements
+
+- **Python 3.10+**
+- **pip** (or [uv](https://docs.astral.sh/uv/))
+- One of the following AI backends:
+  - [Claude CLI](https://docs.anthropic.com/en/docs/claude-code) or an Anthropic API key
+  - [Gemini CLI](https://github.com/google-gemini/gemini-cli) or a Google API key
+  - An OpenAI API key
+- (Optional) `colcon` — required only if you use the auto-fix loop (`--max-fix-attempts`)
 
 ## Quick Start
 
 ```bash
-# Install
+# 1. Install
 pip install rosforge
 
-# Set your preferred AI backend (stored in ~/.config/rosforge/config.toml)
-rosforge config set engine.name gemini
+# 2. Configure your AI backend
+rosforge config set engine.name claude
 rosforge config set engine.mode cli
 
-# Migrate a single ROS1 package
+# 3. Analyze a package first (no code changes, no AI calls)
+rosforge analyze ./my_ros1_package
+
+# 4. Run the migration
 rosforge migrate ./my_ros1_package -o ./my_ros1_package_ros2
 ```
 
+**Expected output:**
+
+```
+  ╭─ ROSForge ─────────────────────────────────────╮
+  │  AI-driven ROS1 → ROS2 Migration               │
+  ╰─────────────────────────────────────────────────╯
+  Engine: claude-cli
+  Source: /home/user/catkin_ws/src/my_ros1_package
+  Output: /home/user/catkin_ws/src/my_ros1_package_ros2
+  Target distro: humble
+
+  [1/6] Ingest .............. done
+  [2/6] Analyze ............. done
+  [3/6] Transform ........... done
+  [4/6] Report .............. done
+
+  Migration complete. Report: /home/user/.../migration_report.md
+    Files transformed: 12 (8 rule-based, 4 AI-driven)
+    Average confidence: 87%
+    Confidence breakdown: 9 HIGH, 2 MEDIUM, 1 LOW
+
+  Low-confidence files (manual review recommended):
+    • src/legacy_driver.cpp
+```
+
 The migrated package and a `migration_report.md` are written to the output directory.
 
+## How It Works
+
+ROSForge runs a multi-stage pipeline on your ROS1 package:
+
+```mermaid
+graph LR
+    A[Ingest] --> B[Analyze]
+    B --> C[Transform]
+    C --> D{Interactive?}
+    D -->|Yes| E[Review]
+    D -->|No| F{Auto-fix?}
+    E --> F
+    F -->|Yes| G[Validate + Fix Loop]
+    F -->|No| H[Report]
+    G --> H
+```
+
+1. **Ingest** — parses `package.xml`, `CMakeLists.txt`, C++/Python sources, launch files, and msg/srv/action definitions
+2. **Analyze** — resolves dependencies, scores risk, estimates cost, and decides per-file strategy (rule-based vs. AI-driven)
+3. **Transform** — applies static knowledge base mappings first, then sends remaining files to the AI engine
+4. **Review** *(optional, `--interactive`)* — shows a diff for each file; press `a` to accept, `s` to skip, `q` to quit
+5. **Validate** *(optional, `--max-fix-attempts N`)* — runs `colcon build`; if it fails, feeds errors to the AI for auto-fix, up to N retries
+6. **Report** — generates `migration_report.md` with a full changelog, warnings, and manual intervention suggestions
+
 ## Commands
 
 | Command | Description |
 |---|---|
 | `rosforge migrate <path>` | Migrate a single ROS1 package to ROS2 |
 | `rosforge migrate-workspace <path>` | Migrate all packages in a catkin workspace |
-| `rosforge analyze <path>` | Analyze a package and report migration complexity without transforming |
-| `rosforge config set <key> <value>` | Set a configuration value and persist it |
+| `rosforge analyze <path>` | Analyze and report migration complexity (no code changes) |
+| `rosforge config set <key> <value>` | Set a configuration value |
 | `rosforge config get <key>` | Get a single configuration value |
-| `rosforge config list` | Print all current configuration values as JSON |
+| `rosforge config list` | Print all current settings as JSON |
 | `rosforge config reset` | Reset configuration to defaults |
-| `rosforge config path` | Show the path to the configuration file |
-| `rosforge status` | Show the status of an in-progress or completed migration |
+| `rosforge config path` | Show the config file path |
+| `rosforge status` | Show the status of a completed migration |
+
+Configuration is stored at `~/.rosforge/config.toml`.
 
 ## AI Engine Configuration
 
-ROSForge supports three AI backends. Each can run in **cli** mode (calls a locally installed CLI tool, no API key required) or **api** mode (calls the provider's REST API directly, requires an API key).
+ROSForge supports three AI backends. Each can run in **CLI mode** (calls a locally installed CLI tool, no API key required) or **API mode** (calls the provider's REST API, requires an API key).
 
-### Claude
+### Claude (Anthropic)
 
 ```bash
-# CLI mode — requires the Anthropic Claude CLI installed and authenticated
+# CLI mode — requires Claude CLI installed and authenticated
 rosforge config set engine.name claude
 rosforge config set engine.mode cli
 
@@ -68,10 +135,10 @@ rosforge config set engine.mode api
 export ANTHROPIC_API_KEY=sk-ant-...
 ```
 
-### Gemini
+### Gemini (Google)
 
 ```bash
-# CLI mode — requires the Google Gemini CLI installed and authenticated
+# CLI mode — requires Gemini CLI installed and authenticated
 rosforge config set engine.name gemini
 rosforge config set engine.mode cli
 
@@ -118,17 +185,44 @@ Build the output with `colcon build` after migration, feed any errors back to th
 rosforge migrate ./my_package --max-fix-attempts 3
 ```
 
-### Custom rules
+### Custom transformation rules
 
-Supply additional or overriding transformation mappings:
+Supply additional or overriding transformation mappings via a YAML file:
 
 ```bash
 rosforge migrate ./my_package --rules custom_rules.yaml
 ```
 
+<details>
+<summary><strong>Example custom_rules.yaml</strong></summary>
+
+```yaml
+# custom_rules.yaml
+version: 1
+
+api_mappings:
+  cpp:
+    "ros::NodeHandle": "rclcpp::Node"
+    "ros::Publisher": "rclcpp::Publisher"
+  python:
+    "rospy.init_node": "rclpy.init"
+    "rospy.Publisher": "rclpy.create_publisher"
+
+package_mappings:
+  "roscpp": "rclcpp"
+  "rospy": "rclpy"
+
+cmake_mappings:
+  "find_package(catkin REQUIRED": "find_package(ament_cmake REQUIRED"
+```
+
+</details>
+
+Custom mappings take precedence over the built-in knowledge base. See the `version: 1` schema for supported keys: `api_mappings.cpp`, `api_mappings.python`, `package_mappings`, `cmake_mappings`.
+
 ### Skip confirmation
 
-Skip the cost-estimate confirmation prompt (useful in CI):
+Skip the cost-estimate confirmation prompt (useful in CI or scripted runs):
 
 ```bash
 rosforge migrate ./my_package --yes
@@ -144,6 +238,8 @@ rosforge migrate ./my_package --distro jazzy
 
 ### Workspace migration
 
+Migrate all packages in a catkin workspace at once:
+
 ```bash
 rosforge migrate-workspace ./catkin_ws -o ./ros2_ws --engine gemini --yes
 ```
@@ -154,7 +250,7 @@ rosforge migrate-workspace ./catkin_ws -o ./ros2_ws --engine gemini --yes
 # Rich table output in the terminal
 rosforge analyze ./my_package
 
-# Machine-readable JSON
+# Machine-readable JSON (ideal for CI)
 rosforge analyze ./my_package --json
 
 # Save JSON report to file
@@ -234,51 +330,110 @@ rosforge-migrate:
 | 1 | Failure |
 | 2 | Completed with warnings (set `fail-on-warnings` to treat as failure) |
 
-## Custom Rules
+## Troubleshooting
 
-Create a YAML file to add or override transformation mappings:
+### "Engine not available" error
 
-```yaml
-# custom_rules.yaml
-version: 1
+Make sure the engine CLI is installed and on your `PATH`:
 
-api_mappings:
-  cpp:
-    "ros::NodeHandle": "rclcpp::Node"
-    "ros::Publisher": "rclcpp::Publisher"
-  python:
-    "rospy.init_node": "rclpy.init"
-    "rospy.Publisher": "rclpy.create_publisher"
+```bash
+# For Claude
+claude --version
 
-package_mappings:
-  "roscpp": "rclcpp"
-  "rospy": "rclpy"
+# For Gemini
+gemini --version
+```
 
-cmake_mappings:
-  "find_package(catkin REQUIRED": "find_package(ament_cmake REQUIRED"
+If using API mode, verify the API key is set:
+
+```bash
+echo $ANTHROPIC_API_KEY   # Should not be empty
+```
+
+### "Command timed out" during migration
+
+Large packages may exceed the default 300-second timeout. Set a longer timeout in the config:
+
+```bash
+rosforge config set engine.timeout_seconds 600
+```
+
+### Auto-fix loop fails immediately
+
+The auto-fix loop requires `colcon` to be installed and on your `PATH`. On Ubuntu:
+
+```bash
+sudo apt install python3-colcon-common-extensions
 ```
 
-Pass the file with `--rules custom_rules.yaml`. Custom mappings take precedence over the built-in knowledge base.
+### "Could not parse JSON from stdout"
+
+This usually means the AI engine returned unexpected output. Try:
+
+1. Run with `--verbose` to see the raw AI response
+2. Switch to a different engine (some models are more reliable for structured output)
+3. Retry — AI responses can vary between runs
+
+### Config file location
+
+ROSForge stores its configuration at `~/.rosforge/config.toml`. To find or reset it:
+
+```bash
+rosforge config path    # Show the file path
+rosforge config reset   # Reset to defaults
+```
 
 ## Development
 
 ```bash
+# Clone and install in development mode
 git clone https://github.com/Rlin1027/ROSForge.git
 cd ROSForge
 pip install -e ".[dev,all]"
-pytest tests/
-```
 
-Lint and type-check:
+# Run the test suite (700+ tests)
+pytest tests/
 
-```bash
+# Lint and type-check
 ruff check src/
+ruff format --check src/
 mypy src/
 ```
 
+### Project structure
+
+```
+src/rosforge/
+  cli/          # Typer CLI commands (migrate, analyze, config, status)
+  config/       # ConfigManager — loads/saves ~/.rosforge/config.toml
+  engine/       # BYOM engine backends (claude, gemini, openai × cli, api)
+  knowledge/    # Static API mapping tables + custom rules loader
+  models/       # Pydantic data models (config, result, report, source)
+  parsers/      # File parsers (Python, C++, CMake, launch XML, msg/srv)
+  pipeline/     # Pipeline stages (ingest, analyze, transform, review, validate, fix, report)
+  templates/    # Jinja2 report templates
+  utils/        # Subprocess helpers, JSON extraction
+tests/
+  unit/         # Unit tests for individual modules
+  integration/  # Integration tests for cross-module workflows
+  e2e/          # End-to-end CLI tests
+  fixtures/     # Sample ROS1 packages for testing
+```
+
+## Roadmap
+
+- [x] R-01~R-05: Core migration pipeline (v0.1.0)
+- [x] R-06: Auto build verification & fix loop (v0.2.0)
+- [x] R-07: Interactive migration mode (v0.2.0)
+- [x] R-08: Batch workspace migration (v0.2.0)
+- [x] R-09: Custom transformation rules (v0.2.0)
+- [x] R-12: CI/CD integration templates (v0.2.0)
+- [ ] R-10: Plugin API — community-contributed domain-specific strategies
+- [ ] R-11: Web Dashboard — visual migration progress and diff viewer
+
 ## Contributing
 
-Contributions are welcome. Please open an issue before submitting a pull request for significant changes. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+Contributions are welcome! Please open an issue before submitting a pull request for significant changes. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
 ## License
 
