chore(cli): cleanup docs and deadcode

.devcontainer/Dockerfile

@@ -64,6 +64,7 @@ RUN --mount=type=cache,target=/root/.cache/uv \
 ENV VIRTUAL_ENV="/workspace/.venv"
 ENV PATH="/workspace/.venv/bin:${PATH}"
 ENV CHIPCOMPILER_OSS_CAD_DIR="/workspace/chipcompiler/thirdparty/oss-cad-suite"
+ENV CHIPCOMPILER_ICS55_PDK_ROOT="/workspace/chipcompiler/thirdparty/icsprout55-pdk"
 RUN echo 'if [ -f /workspace/.venv/bin/activate ]; then source /workspace/.venv/bin/activate; fi' >> /root/.bashrc
 
 

CLAUDE.md

@@ -1,6 +1,6 @@
 # CLAUDE.md
 
-ECC is the EDA toolchain component of ECOS Studio, orchestrating EDA tools (Yosys, ECC-Tools, OpenROAD, Magic, KLayout) for RTL-to-GDS flows. See `docs/architecture.md` for architecture details and `docs/development.md` for workflows.
+ECC is the EDA toolchain component of ECOS Studio, orchestrating EDA tools (Yosys, ECC-Tools, OpenROAD, Magic, KLayout) for RTL-to-GDS flows. See `docs/development.md` for workflows.
 
 For setup, testing, and code quality commands, see [docs/development.md](docs/development.md).
 

README.cn.md

@@ -32,7 +32,7 @@ GUI（ECOS Studio）已迁移至 [ecos-studio](https://github.com/0xharry/ecos-s
 
 ### 安装脚本（推荐）
 
-安装 `ecc` CLI（Linux x86_64，glibc 2.34+）：
+安装 `ecc` CLI（Linux x86_64，glibc 2.34+，fontconfig）：
 
 ```sh
 curl -fsSL http://release.openecos.com/installers/ecc/latest/ecc-installer.sh | sh
@@ -71,7 +71,25 @@ git submodule update --init --recursive
 ### 源码构建
 
 使用 `uv` 进行 Python 开发时，按上述方式（带 `--recursive`）克隆仓库，
-然后参照 [开发指南](docs/development.md) 配置工作区。
+然后配置工作区（源码开发的推荐方式）：
+
+```bash
+uv sync --no-build-isolation-package ecc-dreamplace --no-build-isolation-package ecc-tools-bin --verbose
+```
+
+完整搭建见 [开发指南](docs/development.cn.md)。
+
+如需自己编译可安装的 CLI 包（与官方 release 相同的 PyInstaller 流程）：
+
+```bash
+ECOS_PYINSTALLER_MODE=onedir uv run --no-sync --managed-python \
+  pyinstaller ecc.spec --clean --noconfirm
+# 重建 dist/ecc/（onedir，约 0.9G；首跑会触发 dreamplace 的 cmake 安装，属正常）
+
+# 安装到本机（覆盖现有安装位，如 ~/.local/ecc；PATH 中指向它的软链无需改动）
+rm -rf ~/.local/ecc && mkdir -p ~/.local/ecc && cp -a dist/ecc/. ~/.local/ecc/
+ecc --help            # 验证应有的命令已列出
+```
 
 ## 快速开始
 
@@ -107,7 +125,6 @@ root = "/path/to/icsprout55-pdk"
 
 [flow]
 preset = "rtl2gds" # rtl2gds | syn_sta | synthesis_lec
-run = "default"
 ```
 
 然后校验并运行：
@@ -128,24 +145,27 @@ ecc log --project gcd
 | `ecc init <name>` | 创建项目骨架和 `ecc.toml` |
 | `ecc check` | 校验 RTL、约束、PDK、工具和配置 |
 | `ecc doctor` | 检查主机环境：PDK、yosys（含 slang）和内置工具 |
+| `ecc doc <topic>` | 在终端阅读内置文档（`config` 配置参考、`ug` 用户指南、`tutorial` 教程） |
 | `ecc run` | 运行配置的 RTL-to-GDS 流程 |
 | `ecc status` | 快速查看 run/步骤进度概要 |
 | `ecc log [step]` | 显示可用日志或步骤日志内容 |
 | `ecc config [step]` | 显示解析后的项目或步骤配置 |
 | `ecc migrate` | 将旧版 `runs/` 项目迁移到 manifest 布局 |
 | `ecc param` | 管理参数覆盖（`list`、`show`、`set`、`unset`、`diff`） |
-| `ecc pdk` | 管理 PDK 路径（`setup`、`set-root`、`show`、`unset`） |
+| `ecc pdk` | 管理 PDK 路径（`set-root`、`show`、`unset`） |
+| `ecc project` | 编辑 `ecc.toml` 中的项目声明（`set`、`unset`、`add`、`remove`、`show`） |
+| `ecc workspace` | 从项目配置刷新受管 workspace |
 | `ecc signoff` | 检查签核就绪度并导出签核包 |
 | `ecc report` | 生成设计总结、QoR、签核清单和步骤报告 |
 | `ecc version` | 显示 ECC 运行时和组件版本 |
 | `ecc layout-image` | 将 GDS 文件渲染为版图图像 |
 
 项目命令均接受 `--project <dir>`（默认为当前目录）。大多数命令支持
-`--plain`、`--json` 和 `--jsonl` 输出，便于脚本化。
+`--plain` 输出，便于脚本化。
+
+完整指南随 CLI 分发、可离线阅读：`ecc doc ug --lang cn`（用户指南）、
+`ecc doc config --lang cn`（配置参考）、`ecc doc tutorial --lang cn`（从零上手的教程）。
 
-完整的命令模型——`ecc.toml` 参考、流程预设、步骤级重跑
-（`--resume`、`--from`、`--only`）和参数覆盖——请参阅
-[CLI 设计规范](docs/specification/cli-design.md)。
 
 ## 功能特性
 
@@ -166,14 +186,12 @@ ecc log --project gcd
 ## 文档
 
 - [文档索引](docs/index.md) - 完整导航
-- [CLI 设计规范](docs/specification/cli-design.md) - 命令接口和 `ecc.toml` 参考
-- [架构](docs/architecture.md) - 系统设计和模式
-- [开发指南](docs/development.md) - 配置和工作流
+- [开发指南](docs/development.cn.md) - 配置和工作流
 - [示例](docs/examples/) - 使用示例
 
 ## 参与贡献
 
-欢迎贡献！配置说明请参阅 [开发指南](docs/development.md)。
+欢迎贡献！贡献规则与评审要求见 [CONTRIBUTING.md](CONTRIBUTING.md)，环境搭建见 [开发指南](docs/development.cn.md)。
 
 ## 致谢
 

README.md

@@ -32,7 +32,7 @@ The GUI (ECOS Studio) has been moved to the [ecos-studio](https://github.com/0xh
 
 ### Installer (recommended)
 
-Install the `ecc` CLI (Linux x86_64, glibc 2.34+):
+Install the `ecc` CLI (Linux x86_64, glibc 2.34+, fontconfig):
 
 ```sh
 curl -fsSL http://release.openecos.com/installers/ecc/latest/ecc-installer.sh | sh
@@ -72,8 +72,28 @@ git submodule update --init --recursive
 ### Build from source
 
 For Python development with `uv`, clone the repository as above (with
-`--recursive`), then follow the [Development Guide](docs/development.md) to
-set up the workspace.
+`--recursive`), then set up the workspace — the recommended way to develop
+from source:
+
+```bash
+uv sync --no-build-isolation-package ecc-dreamplace --no-build-isolation-package ecc-tools-bin --verbose
+```
+
+See the [Development Guide](docs/development.md) for the full setup.
+
+To build the installable CLI bundle yourself (the same PyInstaller pipeline
+as the official release):
+
+```bash
+ECOS_PYINSTALLER_MODE=onedir uv run --no-sync --managed-python \
+  pyinstaller ecc.spec --clean --noconfirm
+# rebuilds dist/ecc/ (onedir, ~0.9G; the first run triggers dreamplace's cmake install, which is normal)
+
+# Install locally (overwrite your install location, e.g. ~/.local/ecc;
+# a PATH symlink pointing at it needs no change)
+rm -rf ~/.local/ecc && mkdir -p ~/.local/ecc && cp -a dist/ecc/. ~/.local/ecc/
+ecc --help            # verify the expected commands are listed
+```
 
 ## Quick Start
 
@@ -110,7 +130,6 @@ root = "/path/to/icsprout55-pdk"
 
 [flow]
 preset = "rtl2gds" # rtl2gds | syn_sta | synthesis_lec
-run = "default"
 ```
 
 Then validate and run:
@@ -131,24 +150,28 @@ Run `ecc --help` (or `ecc <command> --help`) for full usage. Common commands:
 | `ecc init <name>` | Create a project skeleton and `ecc.toml` |
 | `ecc check` | Validate RTL, constraints, PDK, tools, and config |
 | `ecc doctor` | Probe host environment: PDK, yosys (+slang), bundled tools |
+| `ecc doc <topic>` | Read the bundled guides (`config` reference, `ug` user guide, `tutorial`) in the terminal |
 | `ecc run` | Run the configured RTL-to-GDS flow (`--preset` overrides for one run) |
 | `ecc status` | Show a quick run/step progress summary |
 | `ecc log [step]` | Show available logs or step log content |
 | `ecc config [step]` | Show resolved project or step configuration |
 | `ecc migrate` | Migrate a legacy `runs/` project to the manifest layout |
 | `ecc param` | Manage parameter overrides (`list`, `show`, `set`, `unset`, `diff`) |
-| `ecc pdk` | PDK path setup (`setup` clones + unzips, `set-root`, `show`, `unset`) |
+| `ecc pdk` | Manage the PDK path (`set-root`, `show`, `unset`) |
+| `ecc project` | Edit project declarations in `ecc.toml` (`set`, `unset`, `add`, `remove`, `show`) |
+| `ecc workspace` | Refresh managed workspaces from project configuration |
 | `ecc signoff` | Inspect readiness and export the signoff package |
 | `ecc report` | Write design-summary, QoR, checklist, and step reports |
 | `ecc version` | Show ECC runtime and component versions |
 | `ecc layout-image` | Render a GDS file into a layout image |
 
 Project commands accept `--project <dir>` (defaults to the current directory).
-Most commands support `--plain`, `--json`, and `--jsonl` output for scripting.
+Most commands support `--plain` output for scripting.
+
+The full guides ship with the CLI and work offline: `ecc doc ug` (user guide,
+`--lang cn` for 中文), `ecc doc config` (configuration reference), and
+`ecc doc tutorial` (step-by-step first flow).
 
-For the full command model — `ecc.toml` reference, flow presets, step-level
-rerun (`--resume`, `--from`, `--only`), and parameter overrides — see the
-[CLI Design Specification](docs/specification/cli-design.md).
 
 ## Features
 
@@ -169,14 +192,14 @@ rerun (`--resume`, `--from`, `--only`), and parameter overrides — see the
 ## Documentation
 
 - [Documentation Index](docs/index.md) - Complete navigation
-- [CLI Design Specification](docs/specification/cli-design.md) - Command surface and `ecc.toml` reference
-- [Architecture](docs/architecture.md) - System design and patterns
 - [Development Guide](docs/development.md) - Setup and workflows
 - [Examples](docs/examples/) - Usage examples
 
 ## Contributing
 
-Contributions welcome! See [Development Guide](docs/development.md) for setup instructions.
+Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for the rules
+and review expectations, and the [Development Guide](docs/development.md) for
+setup instructions.
 
 ## Acknowledgments
 

chipcompiler/cli/app.py

@@ -46,27 +46,20 @@ def root_callback(
 @app.command("version", help="Show ECC runtime, component, and installed tool versions")
 def version_cmd(
     *,
-    json_output: Annotated[bool, typer.Option("--json")] = False,
-    jsonl: Annotated[bool, typer.Option("--jsonl")] = False,
-    plain: Annotated[bool, typer.Option("--plain")] = False,
+    # Machine-readable output for the desktop app; not part of the documented CLI surface.
+    json_output: Annotated[bool, typer.Option("--json", hidden=True)] = False,
 ) -> None:
     payload = version_payload()
     tools = tool_versions()
-    if jsonl:
-        for name in ("ecc", "dreamplace", "ecc_tools"):
-            typer.echo(json.dumps({"component": name, "version": payload[name]}))
-        for name, version in tools.items():
-            typer.echo(json.dumps({"component": name, "version": version}))
-    elif json_output:
+    if json_output:
         typer.echo(json.dumps({**payload, "tools": tools}))
-    elif plain:
-        from chipcompiler.cli.rendering.render import render_plain
-
-        render_plain(({**payload, **tools},))
     else:
         typer.echo(version_text(payload, tools))
 
 
+register_doc_commands(app)
+
+
 @app.command("layout-image", help="Render a GDS file into a layout image")
 def layout_image_cmd(
     gds: Annotated[str, typer.Option("--gds", help="Input GDS path")],
@@ -83,7 +76,6 @@ def layout_image_cmd(
 
 register_project_commands(app)
 register_doctor_commands(app)
-register_doc_commands(app)
 app.add_typer(param_app, name="param")
 app.add_typer(pdk_app, name="pdk")
 app.add_typer(project_app, name="project")

chipcompiler/cli/command_handlers/param.py

@@ -11,6 +11,7 @@
     validate_pdk_target,
     validate_value,
 )
+from chipcompiler.utility.file import write_text_atomic
 
 
 def _manifest_mode_error(ctx: CommandContext) -> CommandResult | None:
@@ -207,7 +208,12 @@ def param_set(args, ctx: CommandContext) -> CommandResult:
                 [error_record("invalid_value", param=key, reason=problem)], exit_code=1
             )
 
-    _write_param_to_toml(config_path, schema, value)
+    try:
+        _write_param_to_toml(config_path, schema, value)
+    except (OSError, ValueError) as exc:
+        return CommandResult.err(
+            [error_record("config_error", param=key, reason=str(exc))], exit_code=1
+        )
 
     return CommandResult.ok(
         [
@@ -255,7 +261,12 @@ def param_unset(args, ctx: CommandContext) -> CommandResult:
             ]
         )
 
-    removed = _remove_param_from_toml(config_path, schema)
+    try:
+        removed = _remove_param_from_toml(config_path, schema)
+    except (OSError, ValueError) as exc:
+        return CommandResult.err(
+            [error_record("config_error", param=key, reason=str(exc))], exit_code=1
+        )
 
     if removed:
         return CommandResult.ok(
@@ -375,9 +386,7 @@ def _write_param_to_toml(config_path: str, schema, value: object) -> None:
         original = f.read()
 
     new_text = toml_edit.set_scoped_key(original, target_table, name, value)
-
-    with open(config_path, "w") as f:
-        f.write(new_text)
+    write_text_atomic(config_path, new_text)
 
 
 def _remove_param_from_toml(config_path: str, schema) -> bool:
@@ -394,6 +403,5 @@ def _remove_param_from_toml(config_path: str, schema) -> bool:
     if result is None:
         return False
 
-    with open(config_path, "w") as f:
-        f.write(result)
+    write_text_atomic(config_path, result)
     return True