rodo-spec 2.2.0 → 2.3.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 RODO contributors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 RODO contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,222 +1,286 @@
-# rodo-spec
-
-[![npm version](https://img.shields.io/npm/v/rodo-spec.svg)](https://www.npmjs.com/package/rodo-spec)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen.svg)](https://nodejs.org)
-
-> **RODO is a way of working, not a gate.**
-> It structures autonomous engineering cycles into predictable, reviewable, and human-aligned iterations through plain Markdown specifications and deterministic CLI automation.
-
----
-
-## Overview
-
-Modern software development often struggles to bridge high-level intentions with concrete agentic or human execution. `rodo-spec` introduces a disciplined protocol and developer toolkit (`rodo`) that captures intent, architecture, constraints, memory, and validation criteria directly in version-controlled Markdown artifacts.
-
-Whether you run purely offline in **method-only mode** or connect with a shared RODO Kanban server, the framework guarantees that agents and developers always operate with full context, clear guardrails, and deterministic testing criteria.
-
----
-
-## Project Layout Tree
-
-When initialized within a repository, RODO organizes agent capabilities, project knowledge, and cycle specifications into a clean, predictable hierarchy:
-
-```text
-.
-├── .agents/
-│   └── skills/
-│       └── rodo/                 # Agent operational skills & execution prompts
-├── rodo/
-│   ├── kit.json                  # RODO workspace configuration & metadata
-│   ├── AGENTS.md                 # Agent personas, capabilities, and constraints
-│   └── <project>/
-│       ├── MAP.md                # System topology, module map, and dependencies
-│       ├── MEMORY.md             # Long-term cross-cycle knowledge & lessons learned
-│       ├── RULES.md              # Invariant project rules and architectural constraints
-│       ├── CHANGELOG.md          # Chronological log of accepted cycle outcomes
-│       └── cycles/
-│           └── NNN-slug/         # Discrete feature/task cycle (e.g., 001-auth-flow)
-│               ├── card.rodo.md  # Standard RODO cycle card metadata & state
-│               ├── simple.md     # High-level overview & developer summary
-│               └── spec.md       # Detailed technical spec, acceptance criteria & tests
-```
-
----
-
-## Installation
-
-### Prerequisites
-
-- **Node.js**: `>= 20.0.0`
-- **npm**, **pnpm**, or **yarn**
-
-### Global Install via npm
-
-```bash
-npm install -g rodo-spec
-```
-
-### Install from Source / GitHub
-
-```bash
-git clone https://github.com/n3xus-ir/rodo-spec.git
-cd rodo-spec
-npm install
-npm run build
-npm link
-```
-
----
-
-## Quick Start (Offline / Method-Only Mode)
-
-You can use RODO as a 100% offline methodology without signing up or connecting to any remote server.
-
-### 1. Initialize your project
-```bash
-rodo init --method-only --project myapp --lang en
-```
-
-### 2. Scaffold your first cycle card
-```bash
-rodo new "My first feature"
-```
-This generates a new cycle directory under `rodo/myapp/cycles/001-my-first-feature/` containing `card.rodo.md`, `simple.md`, and `spec.md`.
-
-### 3. Validate your specifications
-Check that your specifications meet the schema, invariants, and constraints:
-```bash
-rodo validate --strict
-```
-
-### 4. Resume or inspect current progress
-```bash
-rodo resume
-```
-
-### 5. Run tests associated with the active card
-```bash
-rodo test
-```
-
-### 6. Review cycle and workspace health
-```bash
-rodo status
-rodo doctor
-```
-
----
-
-## Commands Table
-
-The CLI executable is `rodo`. Below is the complete reference of core commands:
-
-| Command | Arguments / Flags | Description |
-| :--- | :--- | :--- |
-| `rodo init` | `[--method-only] [--project <name>] [--lang <en\|fa>] [--create-board] [--server <url>]` | Initializes RODO structure, configs, and agent templates in the current repository. |
-| `rodo new` | `"<title>" [--slug <slug>] [--project <name>]` | Creates a new cycle card directory with standard RODO specification templates. |
-| `rodo resume` | `[card]` | Resumes context on an active or specified cycle card for agent or human execution. |
-| `rodo validate` | `[--strict] [--project <name>]` | Validates Markdown files, schemas, links, and invariants across project cycles. |
-| `rodo test` | `[card]` | Executes the verification steps and tests declared in the card's `spec.md`. |
-| `rodo status` | `[--local] [--project <name>]` | Displays the current cycle state, progression, and work-in-progress diagnostics. |
-| `rodo sync` | `[--server <url>] [--force]` | Synchronizes local cards and states with the remote RODO board. |
-| `rodo doctor` | _None_ | Diagnoses environment issues, missing dependencies, and directory configuration health. |
-| `rodo login` | `[--server <url>]` | Authenticates CLI credentials with a remote RODO Kanban board server. |
-| `rodo logout` | _None_ | Clears stored session tokens and remote authentication state. |
-| `rodo version` | _None_ | Displays the current version of the CLI and core protocols. |
-
----
-
-## Method-Only vs. Board Sync
-
-RODO supports two operational modes:
-
-### 1. Method-Only Mode (`--method-only`)
-- Operates entirely offline.
-- No network traffic, accounts, or API keys required.
-- Ideal for personal open-source projects, air-gapped environments, or local-first agent workflows.
-- Git remains the single source of truth.
-
-### 2. Board Sync Mode
-- Synchronizes your local Markdown cards and state transitions with a collaborative RODO visual board.
-- Enabled by specifying a board server during `init` or running `rodo sync`.
-- **Default Server**: `https://rodo.n3xus.ir`
-- **Configuring the Server**:
-  - Pass the flag explicitly: `--server https://rodo.n3xus.ir`
-  - Or set the environment variable:
-    ```bash
-    export RODO_SERVER="https://rodo.n3xus.ir"
-    ```
-
----
-
-## Monorepo Packages
-
-This repository is maintained as a monorepo consisting of modular, reusable packages:
-
-- **[`packages/protocol`](packages/protocol)**: Core data models, state transition machines, invariant validators, and protocol constants.
-- **[`packages/card-format`](packages/card-format)**: Markdown AST parsers, frontmatter serialisers, and schema definitions for `card.rodo.md`, `simple.md`, and `spec.md`.
-- **[`packages/rodo-kit`](packages/rodo-kit)**: High-level workspace utilities, template engines, scaffolders, and file-system helpers.
-- **[`packages/cli`](packages/cli)**: The end-user command-line binary (`rodo`) implementing the commands and interface.
-
----
-
-## License
-
-This project is licensed under the [MIT License](LICENSE).
-
----
-
-## راهنمای سریع (فارسی)
-
-رودو (**RODO**) یک متدولوژی و جعبه‌ابزار استاندارد برای توسعه نرم‌افزار با همکاری برنامه‌نویسان و هوش مصنوعی است. رودو یک دروازه سخت‌گیرانه نیست، بلکه روشی ساختاریافته است تا تمام مراحل ایده، مشخصات فنی، معماری و آزمون‌ها در قالب فایل‌های ساده و شفاف Markdown ثبت، اعتبارسنجی و اجرا شوند.
-
-### ۱. نصب
-
-برای استفاده از ابزار خط فرمان `rodo`، نسخه ۲۰ یا بالاتر Node.js را نصب کرده و دستور زیر را اجرا کنید:
-
-```bash
-npm i -g rodo-spec
-```
-
-### ۲. شروع سریع بدون سرور (حالت محلی / Method-Only)
-
-اگر می‌خواهید بدون نیاز به سرور و به صورت کاملاً آفلاین روی مخزن محلی خود کار کنید:
-
-```bash
-# راه‌اندازی ساختار رودو به زبان فارسی
-rodo init --method-only --project myapp --lang fa
-```
-
-### ۳. شروع سریع همراه با سرور و تخته RODO
-
-اگر تمایل دارید کارت‌ها و چرخه‌های کاری با سرور متمرکز هماهنگ شوند:
-
-```bash
-# ورود به حساب کاربری
-rodo login
-
-# راه‌اندازی پروژه و ساخت تخته کاری
-rodo init --project myapp --create-board
-
-# همگام‌سازی وضعیت‌ها با سرور
-rodo sync
-```
-
-> **نکته:** آدرس پیش‌فرض سرور `https://rodo.n3xus.ir` است که می‌توانید آن را از طریق متغیر محیطی `RODO_SERVER` یا آرگومان `--server` تغییر دهید.
-
-### ۴. ساخت کارت چرخه جدید و اعتبارسنجی
-
-برای تعریف یک تسک یا قابلیت جدید:
-
-```bash
-# ساخت کارت جدید با اسلاگ اختصاصی
-rodo new "پیاده‌سازی احراز هویت" --slug auth-feature
-
-# بررسی صحت فایل‌ها و عدم وجود خطای ساختاری
-rodo validate --strict
-
-# اجرای آزمون‌ها و بررسی سلامت محیط
-rodo test
-rodo doctor
-```
+# rodo-spec
+
+[![npm version](https://img.shields.io/npm/v/rodo-spec.svg)](https://www.npmjs.com/package/rodo-spec)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen.svg)](https://nodejs.org)
+
+> **RODO is a way of working, not a gate.**
+> It structures autonomous engineering cycles into predictable, reviewable, and human-aligned iterations through plain Markdown specifications and deterministic CLI automation.
+
+---
+
+## Overview
+
+Modern software development often struggles to bridge high-level intentions with concrete agentic or human execution. `rodo-spec` introduces a disciplined protocol and developer toolkit (`rodo`) that captures intent, architecture, constraints, memory, and validation criteria directly in version-controlled Markdown artifacts.
+
+Whether you run purely offline in **method-only mode** or connect with a shared RODO Kanban server, the framework guarantees that agents and developers always operate with full context, clear guardrails, and deterministic testing criteria.
+
+---
+
+## Project Layout Tree
+
+When initialized within a repository, RODO organizes agent capabilities, project knowledge, and cycle specifications into a clean, predictable hierarchy:
+
+```text
+.
+├── AGENTS.md                         # Pointer to the RODO skill for AI assistants
+├── .agents/
+│   └── skills/
+│       └── rodo/                     # Agent operational skills, playbooks & templates
+└── rodo/
+    ├── kit.json                      # Installed RODO kit version & file checksums
+    └── <project>/
+        ├── project.json              # Project settings & optional board binding (no secrets)
+        ├── MAP.md                    # System topology, current state, done & next cycles
+        ├── MEMORY.md                 # Append-only cross-cycle decisions & rationale
+        ├── RULES.md                  # Human-readable guide to the RODO method
+        ├── CHANGELOG.md              # One-line log for small changes that need no card
+        ├── project/
+        │   ├── brief.md              # Plain-language project overview
+        │   ├── architecture.md       # Stack, components, data model & test setup
+        │   └── glossary.md           # Domain terms and definitions
+        └── cycles/
+            └── NNN-slug/             # Discrete feature/task cycle (e.g., 001-auth-flow)
+                ├── card.rodo.md      # Cycle card metadata, checklist, refs & progress notes
+                ├── simple.md         # Plain-language summary of what the user gets
+                ├── spec.md           # Technical rules (R1, R2...), acceptance & doc impact
+                ├── design.md         # Architectural design (for major changes)
+                └── acceptance.feature # Optional Gherkin scenarios tagged @R1, @R2...
+```
+
+---
+
+## Installation
+
+### Prerequisites
+
+- **Node.js**: `>= 20.0.0`
+- **npm**, **pnpm**, or **yarn**
+
+### Global Install via npm (Recommended)
+
+```bash
+npm install -g rodo-spec
+```
+
+Or run directly with `npx`:
+
+```bash
+npx rodo-spec --help
+```
+
+### Install from Source / GitHub
+
+```bash
+git clone https://github.com/alishafiee1/rodo-spec.git
+cd rodo-spec
+pnpm install
+pnpm run build
+npm link --workspace=packages/cli
+```
+
+---
+
+## Quick Start (Offline / Method-Only Mode)
+
+You can use RODO as a 100% offline methodology without signing up or connecting to any remote server. In method-only mode, `card.rodo.md` files are tracked directly in Git alongside `simple.md` and `spec.md`.
+
+### 1. Initialize your project
+```bash
+rodo init --method-only --project myapp --lang en
+```
+
+### 2. Scaffold your first cycle card
+```bash
+rodo new "My first feature"
+```
+This generates `rodo/myapp/cycles/001-my-first-feature/` containing `card.rodo.md`, `simple.md`, and `spec.md` (add `--major` to also generate `design.md` and `acceptance.feature`, or `--slug <kebab-slug>` when the title is non-Latin).
+
+### 3. Validate your specifications
+Check that your cards and cycle documents meet all format rules:
+```bash
+rodo validate --strict
+```
+
+### 4. Resume or inspect current progress
+```bash
+rodo resume
+```
+
+### 5. Run tests associated with the active card
+```bash
+rodo test
+```
+
+### 6. Review cycle and workspace health
+```bash
+rodo status --local
+rodo doctor
+```
+
+---
+
+## Connecting to a RODO Board (3 Ways)
+
+You can connect an existing method-only project—or initialize a brand-new project—with a RODO Kanban board server (default: `https://rodo.n3xus.ir`) at any time. Connecting binds `rodo/<project>/project.json` to the board and runs the initial sync automatically.
+
+### Way 1: One-Step Connect Code from the Web Board (Fastest)
+Open your board on the web (`https://rodo.n3xus.ir`), click **"Connect Device" («اتصال دستگاه»)** to generate a one-time code, and run:
+```bash
+rodo init --project myapp --connect RODO-XXXX-XXXX
+```
+This logs in your device, binds `rodo/myapp/` to that exact board, and syncs all cards in a single step—no separate `rodo login` needed.
+
+### Way 2: Log In & Bind to an Existing Board (Interactive List or Board ID)
+```bash
+# 1. Authenticate your device (via browser device code or --connect <code>)
+rodo login
+
+# 2a. Pick a board interactively from your workspaces
+rodo init --project myapp
+
+# 2b. Or bind directly by passing the board ID
+rodo init --project myapp --board <boardId>
+```
+
+### Way 3: Log In & Create a New Board from the Terminal
+If your device token was approved with board-creation permission (`boards:create`):
+```bash
+rodo login
+rodo init --project myapp --create-board
+```
+You will be prompted to select the workspace and project and confirm the new board title.
+
+### Ongoing Synchronization
+Once connected, run `rodo sync` at the start and end of every work session:
+```bash
+rodo sync
+```
+
+- **Default Server**: `https://rodo.n3xus.ir`
+- **Custom Server**: Pass `--server <url>` or set `export RODO_SERVER="https://rodo.n3xus.ir"`.
+
+---
+
+## Commands Table
+
+The CLI executable is `rodo`. Global flags `--project <slug>`, `--lang <fa|en>`, `--json`, and `--verbose` can be used with any command.
+
+| Command | Arguments / Flags | Description |
+| :--- | :--- | :--- |
+| `rodo init` | `[--method-only] [--project <slug>] [--name <name>] [--lang <fa\|en>] [--connect <code>] [--board <id>] [--create-board] [--server <url>] [--no-kit-update] [--dry-run] [--yes-files]` | Installs or updates the RODO kit, scaffolds `rodo/<project>/`, and optionally binds & syncs with a board. |
+| `rodo new` | `"<title>" [--slug <kebab-slug>] [--major] [--dry-run] [--project <slug>]` | Creates the next `rodo/<project>/cycles/NNN-slug/` folder with `card.rodo.md`, `simple.md`, and `spec.md`. |
+| `rodo resume` | `[card] [--full] [--project <slug>]` | Prints compact context of the active or specified card for an AI session (`--full` includes architecture & `simple.md`). |
+| `rodo validate` | `[paths...] [--strict] [--project <slug>]` | Validates card files and cycle references (`--strict` exits with code `1` on errors for CI). |
+| `rodo test` | `[card] [--adapter <web\|api\|cli\|mobile\|iot\|other>] [--project <slug>]` | Runs the card's test command and tracks repeated failure signatures (`RODO_STUCK`). |
+| `rodo status` | `[--local] [--project <slug>]` | Displays cards and their state side-by-side (board vs. local, or `--local` offline). |
+| `rodo sync` | `[--offline] [--dry-run] [--pull-only] [--push-only] [--confirm-archive] [--check] [--project <slug>]` | Pulls, merges, pushes, and writes back card files with the bound RODO board (`--offline` validates only). |
+| `rodo doctor` | `[--project <slug>]` | Runs read-only health checks on Node, Git, kit files, `.gitignore`, server connectivity, and cards. |
+| `rodo login` | `[--server <url>] [--connect <code>] [--rotate]` | Logs in with a browser device code or a one-time `--connect` code (`--rotate` replaces the current token). |
+| `rodo logout` | `[--server <url>]` | Revokes this device token on the server and deletes the local token. |
+| `rodo devices` | `[--server <url>]` | Shows the web URL for managing connected devices (`<server>/devices`) and this device's token scopes. |
+| `rodo version` | `[--json]` | Displays the CLI version, bundled kit version, and Node.js runtime version. |
+
+---
+
+## Monorepo Packages
+
+This repository is maintained as a monorepo consisting of modular packages:
+
+- **[`packages/protocol`](packages/protocol)**: Wire contract, sync API payload shapes, and card status rules between the CLI and a RODO board server.
+- **[`packages/card-format`](packages/card-format)**: Parser, canonical serializer, 3-way merge engine, secret scanner, and validator for `*.rodo.md` files.
+- **[`packages/rodo-kit`](packages/rodo-kit)**: Bundled AI skill (`.agents/skills/rodo/`), Persian & English project templates, and migration manifest.
+- **[`packages/cli`](packages/cli)**: The end-user command-line binary (`rodo`) published to npm as `rodo-spec`.
+
+---
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).
+
+---
+
+## راهنمای سریع (فارسی)
+
+رودو (**RODO**) یک روش کار و جعبه‌ابزار خط فرمان (`rodo`) برای توسعهٔ ساختاریافتهٔ نرم‌افزار با همکاری انسان و هوش مصنوعی است. RODO یک دروازهٔ مسدودکننده نیست؛ هیچ ابزاری جلوی `commit` یا ادامهٔ کار را نمی‌گیرد، بلکه باعث می‌شود نقشهٔ پروژه (`MAP.md`)، تصمیم‌ها (`MEMORY.md`)، توضیح ساده (`simple.md`) و مشخصات فنی (`spec.md`) همیشه با کد هماهنگ بمانند.
+
+### ۱. نصب
+
+پیشنیاز: **Node.js نسخهٔ ۲۰ یا بالاتر**. برای نصب سراسری از طریق `npm`:
+
+```bash
+npm i -g rodo-spec
+```
+
+### ۲. شروع سریع بدون سرور (حالت آفلاین / Method-Only)
+
+اگر می‌خواهید بدون نیاز به سرور یا حساب کاربری، روی مخزن گیت خود کار کنید (در این حالت فایل‌های `card.rodo.md` هم داخل گیت ذخیره می‌شوند):
+
+```bash
+# ۱. راه‌اندازی کیت و پوشهٔ پروژه به زبان فارسی
+rodo init --method-only --project myapp --lang fa
+
+# ۲. ساخت اولین چرخه و کارت جدید (برای عناوین فارسی حتماً --slug انگلیسی بدهید)
+rodo new "پیاده‌سازی احراز هویت" --slug auth-feature
+
+# ۳. اعتبارسنجی ساختار کارت‌ها و مشاهدهٔ وضعیت محلی
+rodo validate --strict
+rodo status --local
+```
+
+### ۳. اتصال به سرور و تختهٔ RODO (به ۳ روش)
+
+هر زمان که بخواهید کارت‌های پروژه را روی برد وب RODO (به‌طور پیش‌فرض `https://rodo.n3xus.ir`) ببینید و همگام‌سازی کنید، می‌توانید یکی از سه روش زیر را به کار ببرید:
+
+#### روش اول: اتصال تک‌مرحله‌ای با کد اتصال از داخل برد وب (سریع‌ترین روش)
+وارد برد خود در وب‌سایت `https://rodo.n3xus.ir` شوید، روی دکمهٔ **«اتصال دستگاه»** کلیک کنید تا کد یک‌بارمصرف ساخته شود و سپس در ترمینال بزنید:
+
+```bash
+rodo init --project myapp --connect RODO-XXXX-XXXX
+```
+این دستور هم‌زمان ورود دستگاه، اتصال پروژهٔ `rodo/myapp/` به همان برد و اولین همگام‌سازی (`sync`) کارت‌ها را انجام می‌دهد و نیازی به اجرای جداگانهٔ `rodo login` ندارد.
+
+#### روش دوم: ورود و اتصال به برد موجود (انتخاب از لیست یا با شناسهٔ برد)
+```bash
+# ۱. ورود به حساب کاربری (با کد تایید مرورگر)
+rodo login
+
+# ۲-الف. نمایش لیست بردهای شما در ترمینال و انتخاب شمارهٔ برد
+rodo init --project myapp
+
+# ۲-ب. یا اتصال مستقیم با دادن شناسهٔ برد (boardId)
+rodo init --project myapp --board <boardId>
+```
+
+#### روش سوم: ورود و ساخت تختهٔ (برد) جدید از داخل ترمینال
+اگر هنگام تایید دستگاه در وب، تیک مجوز ساخت برد (`boards:create`) را زده باشید:
+```bash
+rodo login
+rodo init --project myapp --create-board
+```
+ابزار از شما فضای کاری و پروژه را می‌پرسد و پس از تایید نام برد، تختهٔ جدید را روی سرور می‌سازد و کارت‌های محلی را به آن ارسال می‌کند.
+
+#### همگام‌سازی مستمر در طول کار (`rodo sync`)
+پس از اتصال به برد، در شروع و پایان هر جلسهٔ کاری دستور زیر را اجرا کنید تا تغییرات وب و فایل‌های محلی با هم ادغام و همگام شوند:
+
+```bash
+rodo sync
+```
+
+> **نکته:** آدرس پیش‌فرض سرور `https://rodo.n3xus.ir` است. برای استفاده از سرور دیگر می‌توانید متغیر محیطی `RODO_SERVER` را تنظیم کنید یا فلگ `--server <url>` را بدهید.
+
+### ۴. دستورات پرکاربرد روزانه
+
+```bash
+# دریافت خلاصهٔ وضعیت و زمینهٔ کارت فعال برای دادن به دستیار هوش مصنوعی
+rodo resume
+
+# اجرای دستور تست تعریف‌شده برای کارت و پایش شکست‌های تکراری
+rodo test
+
+# بررسی سلامت کلی محیط، گیت، کیت و اتصال سرور
+rodo doctor
+
+# مشاهدهٔ آدرس مدیریت دستگاه‌های متصل و وضعیت توکن فعلی
+rodo devices
+```

package/dist/index.js

@@ -11057,16 +11057,16 @@ function ensureBlock(path, block, kit20Hashes, importsAgents, dryRun = false) {
 // package.json
 var package_default = {
   name: "rodo-spec",
-  version: "2.2.0",
+  version: "2.3.0",
   description: "RODO method CLI \u2014 install the kit, manage cards, sync with the board",
   license: "MIT",
   type: "module",
   repository: {
     type: "git",
-    url: "https://github.com/n3xus-ir/rodo-spec.git",
+    url: "https://github.com/alishafiee1/rodo-spec.git",
     directory: "packages/cli"
   },
-  homepage: "https://github.com/n3xus-ir/rodo-spec#readme",
+  homepage: "https://github.com/alishafiee1/rodo-spec#readme",
   keywords: [
     "rodo",
     "rodo-spec",
@@ -14022,7 +14022,7 @@ async function runInit(ctx, a) {
     out.line(`project rodo/${slug2}/: ${existsSync14(join14(projectDir, "project.json")) ? "exists (missing files would be added)" : "would be created"}`);
   } else {
     const isNew = !existsSync14(join14(projectDir, "project.json"));
-    const lang = isNew ? await chooseLanguage(ctx) : "fa";
+    const lang = isNew ? await chooseLanguage(ctx) : readProject(projectDir, slug2).project?.language.simple ?? "fa";
     const created = scaffoldProject(root, slug2, a.name ?? slug2, lang);
     if (isNew) data.language = lang;
     out.line(created.length ? `rodo/${slug2}/: created ${created.length} file(s)` : `rodo/${slug2}/: nothing to add`);
@@ -14769,7 +14769,18 @@ async function runTest(ctx, query, a) {
 }
 
 // src/commands/validate.ts
-import { resolve as resolve3 } from "path";
+import { existsSync as existsSync18, readFileSync as readFileSync17 } from "fs";
+import { join as join19, resolve as resolve3 } from "path";
+var PROJECT_DOC_LIMITS = { "project/project-overview.md": 500, "project/how-it-works.md": 900 };
+var wordCount = (text) => text.replace(/<!--[\s\S]*?-->/g, " ").split(/\s+/).filter(Boolean).length;
+function longProjectDocs(dir) {
+  return Object.entries(PROJECT_DOC_LIMITS).flatMap(([path, limit]) => {
+    const abs = join19(dir, path);
+    if (!existsSync18(abs)) return [];
+    const words = wordCount(readFileSync17(abs, "utf8"));
+    return words > limit ? [{ path, code: "PROJECT_DOC_TOO_LONG", line: null, message: `PROJECT_DOC_TOO_LONG: ${words} words, the limit is ${limit}; shorten it` }] : [];
+  });
+}
 async function runValidate(ctx, paths, o = {}) {
   const { d, refs } = load(ctx, false);
   const only = paths.map((p) => resolve3(ctx.cwd, p));
@@ -14778,6 +14789,8 @@ async function runValidate(ctx, paths, o = {}) {
   for (const ref of refs) {
     const cards = scanCards(d.root, ref, only);
     const s = sum(cards);
+    const docs = only.length || ref.legacy ? [] : longProjectDocs(ref.dir);
+    s.warnings += docs.length;
     total.files += s.files;
     total.errors += s.errors;
     total.warnings += s.warnings;
@@ -14785,6 +14798,10 @@ async function runValidate(ctx, paths, o = {}) {
     ctx.out.line(`rodo/${ref.legacy ? "" : ref.slug}  \u25B8 ${s.files} files \xB7 errors ${s.errors} \xB7 warnings ${s.warnings}`);
     printFindings(ctx, cards);
     for (const c of cards) files.push({ project: ref.slug, path: c.path, errors: c.errors.map(slim2), warnings: c.warnings.map(slim2) });
+    for (const f of docs) {
+      ctx.out.line(`  ${mark.warn} ${f.path}  ${f.message}`);
+      files.push({ project: ref.slug, path: f.path, errors: [], warnings: [{ code: f.code, line: f.line, message: f.message }] });
+    }
   }
   ctx.out.flush({ version: 2, files, summary: total });
   return o.strict && total.errors > 0 ? 1 : 0;

package/dist/kit/.agents/skills/rodo/SKILL.md

@@ -5,7 +5,7 @@ description: RODO project method. Use whenever the repo has a rodo/ folder or *.
 
 > یادداشت فارسی: این مهارت برای AI است. نسخهٔ انسانی همین قواعد در `rodo/<project>/RULES.md` است. RODO فقط «روش کار» است: هیچ ابزاری جلوی commit، تست یا کار را نمی‌گیرد.
 
-# RODO method (kit 2.2.0)
+# RODO method (kit 2.3.0)
 
 RODO is a way of working, not a gate. Nothing blocks a commit, a test or a status. You follow it because it keeps the project understandable for the user, for teammates and for the next AI session.
 
@@ -86,6 +86,7 @@ A card may have `scope: {allowed: [...], forbidden: [...]}`. Stay inside `allowe
 | The repo has code but no `rodo/<project>/` yet | `onboarding.md` |
 | Typo, style, refactor or a fix that does not change described behaviour | `small-change.md` |
 | You write or fix tests (optional, recommended) | `testing.md` |
+| You write or update `project/project-overview.md` or `project/how-it-works.md` | `project-docs.md` |
 
 ## Workflow levels
 
@@ -122,7 +123,7 @@ Do not turn ordinary clarification questions into `## Decision:` sections, and d
 
 | Kind | Files | Rule |
 |---|---|---|
-| **CURRENT** (canonical) | `rodo/<project>/project/*`, `MAP.md`, `MEMORY.md` | Must describe the code as it is now. Update them in the same work. `MEMORY.md` is append-only: add a new line that says which line it replaces; never rewrite old lines. |
+| **CURRENT** (canonical) | `rodo/<project>/project/*`, `MAP.md`, `MEMORY.md` | Must describe the code as it is now. Update them in the same work. `MEMORY.md` is append-only: add a new line that says which line it replaces; never rewrite old lines. One exception: a planned part in `project-overview.md` (unticked) or `how-it-works.md` (marked `(planned)`) may describe work not built yet (`project-docs.md`). |
 | **ACTIVE CYCLE** | the docs of the card you are working on (`simple.md`, `spec.md`, `design.md`, `acceptance.feature`) | Must match the code when the card is done. |
 | **HISTORICAL** | docs of `done` and `cancelled` cycles | Never rewritten. A later card refers to them; a new decision goes into the new card and `MEMORY.md`. |
 
@@ -142,6 +143,8 @@ Run the checks that fit this change with the project's own tools; RODO runs noth
         project.json                  board binding and settings (no secrets)
         MAP.md  MEMORY.md  RULES.md  CHANGELOG.md
         project/{brief,architecture,glossary}.md
+        project/project-overview.md   the project for a client, parts with ticks
+        project/how-it-works.md       how each part works, for a beginner
         cycles/NNN-slug/
           card.rodo.md                the card (synced with the board, not in git)
           simple.md                   plain explanation (shown read-only on the web)
@@ -163,6 +166,6 @@ Card format details: the comments in `templates/card.rodo.md` and `rodo validate
 | `rodo new "<title>"` | create the next cycle folder with `card.rodo.md`, `simple.md`, `spec.md` (`--major` adds `design.md` and `acceptance.feature`) |
 | `rodo validate` | check card files (never blocks; `--strict` exits 1 on errors, for CI) |
 | `rodo doctor` | find setup problems |
-| `rodo init` | install/update the kit, bind a board. **Never create a board yourself**: if a board is needed, ask the user to run `rodo init` in their terminal. |
+| `rodo init` | install/update the kit, bind a board (`--method-only`, `--connect <code>`, `--board <id>`, `--create-board`). **Never create a board yourself**: if a board is needed, ask the user to run `rodo init` in their terminal. |
 
 Optional, if available in the project: Graphify (code map, for Documentation Impact and finding affected code) and Context7 (current library docs). Never install them yourself; RODO works without them.

package/dist/kit/.agents/skills/rodo/coder.md

@@ -71,7 +71,8 @@ The folder does not move.
 1. Card: `status: done`.
 2. `MAP.md`: add the cycle under `## انجام‌شده` (one line, link to simple.md or the card folder) and update "الان کجاییم".
 3. `MEMORY.md`: append each `## Decisions` line of spec.md as `- YYYY-MM-DD — <decision>. چون <reason>. (cycle NNN)`.
-4. Commit the MAP and MEMORY change. Later changes to this behaviour need a new card; changes that do not touch behaviour go to `small-change.md`.
+4. `project/project-overview.md` and `project/how-it-works.md`: make them match what was built and tick the part if all of it is finished (`project-docs.md`).
+5. Commit the MAP, MEMORY and project docs change. Later changes to this behaviour need a new card; changes that do not touch behaviour go to `small-change.md`.
 
 ## Rules
 

package/dist/kit/.agents/skills/rodo/onboarding.md

@@ -8,7 +8,7 @@ Goal: create `rodo/<project>/` so the project can follow the method, without cha
 
 1. **Read, do not write.** Read README, existing docs, package files, folder structure, git log (last ~100 commits), and TODO/FIXME comments. Skim code by folder; do not read every file.
 2. **Create the skeleton**: run `rodo init --method-only --project <slug>` (if the CLI is installed), or copy `project-template/` into `rodo/<slug>/` yourself. It never overwrites an existing file. Set `language` in `project.json` if the user wants other languages.
-3. **brief.md and architecture.md**: describe what exists today. Mark guesses with `(حدس)` so the user can confirm.
+3. **brief.md and architecture.md**: describe what exists today. Mark guesses with `(حدس)` so the user can confirm. Then write `project/project-overview.md` and `project/how-it-works.md` the same way (`project-docs.md`), ticking only parts that already work.
 4. **MEMORY.md**: decisions visible in the code or docs (framework, database, auth method...). One line each with the reason if known, else `چون: نامعلوم`.
 5. **Finished work → done cycles.** For each finished feature a user can see, create `rodo/<project>/cycles/NNN-slug/` with:
    - `simple.md` whose FIRST line is `<!-- rodo:onboarded -->`, then 3-6 simple lines;

package/dist/kit/.agents/skills/rodo/planner.md

@@ -24,6 +24,7 @@ Yes, for every new feature, change or improvement, and for every change to behav
 - List the current documents this change will make wrong or must extend.
 - Use `MAP.md`, `MEMORY.md`, `project/*`, the active cycle, the card's refs, and a code search (Graphify or similar, if available in the project).
 - Write the list in `spec.md` `## Documentation Impact` (`- <path> — <what changes>`, or `- none — <why>`).
+- **Project docs first:** if a new feature or major change does not fit `project/project-overview.md` or `project/how-it-works.md`, update them before BUILD, following `project-docs.md`. If they are still templates, fill them first.
 - QUICK: do this in your head and fix any doc you made wrong (small-change.md).
 
 ## Classify

package/dist/kit/.agents/skills/rodo/project-docs.md

@@ -0,0 +1,41 @@
+> یادداشت فارسی: قانون نگارش دو سند سادهٔ پروژه: `project-overview.md` برای کارفرما و `how-it-works.md` برای یک مبتدی. این سندها همیشه کوتاه می‌مانند و پیش از شروع کار با طرح تازه هماهنگ می‌شوند. همهٔ مسیرها نسبت به `rodo/<project>/` هستند.
+
+# Project docs playbook
+
+Two short documents explain the whole project to people. Write them in the language of `language.simple` in `project.json`. They do not replace `brief.md` or `architecture.md`; those stay as they are.
+
+| File | Reader | Answers | Limit |
+|---|---|---|---|
+| `project/project-overview.md` | the client | what is this project, what parts does it have, which are finished | 500 words |
+| `project/how-it-works.md` | the owner, a beginner who builds with AI | what is it built from, how does each part work, what does each part make easier | 900 words |
+
+## project-overview.md
+
+- Write it like a plan you hand to a client. Short sentences, no jargon.
+- **No technology names** (no framework, database or service names). Describe what the user gets.
+- Sections: what this project is, goals, parts of the project.
+- One line per part: `- [ ] **Name**: two or three sentences`. Name parts the way a client would, not after cycles or folders.
+- Planned parts stay visible, unticked. Cancelled parts are removed.
+- `[x]` means the part is finished and works. Never tick a part that is only planned, half done or untested when it has tests.
+
+## how-it-works.md
+
+- Write like an experienced engineer explaining to an intern, in plain words. Technology names are welcome; explain each one the first time it appears.
+- Start with the big picture: a few sentences on what happens when a user does something, and which part talks to which.
+- One `##` section per part or piece of infrastructure, each answering: what is it and how does it work, and what does it make easier (what would be hard without it).
+- Use one example from this project in place of a general definition.
+- Depth follows importance: a main part may get a paragraph, a small helper one or two sentences.
+- Never write secrets, passwords, keys or server addresses that are not public.
+
+## When to update them
+
+1. **Planning (before work starts).** In Documentation Impact, ask: does this new feature or major change fit what these two files say? If not, update them before BUILD. A new part goes in the overview unticked. In `how-it-works.md` mark a part that does not exist yet with `(planned)`. List both files in `spec.md` `## Documentation Impact`.
+2. **Closing a card.** Make the text match what was really built, remove `(planned)`, and tick the part in the overview if all of it is finished. A part that needs more cards stays unticked.
+3. **QUICK changes** do not touch these files, unless a sentence in them became false.
+4. **Empty or template files** (they still contain `{{`): the next planner fills them from the code and the current docs before planning its card. Mark anything you could not confirm with `(guess)`, or `(حدس)` in Persian.
+
+## Staying short
+
+- Never let a file grow past its limit. `rodo validate` warns with `PROJECT_DOC_TOO_LONG`; it never blocks anything.
+- To add something when a file is full, shorten or merge what is there. Do not add a second file or an appendix.
+- These files describe the project as a whole. History belongs in `MAP.md`, decisions in `MEMORY.md`, details in `architecture.md` and `spec.md`.

package/dist/kit/KIT_VERSION

@@ -1 +1 @@
-2.2.0
+2.3.0

package/dist/kit/MIGRATION.md

@@ -2,6 +2,16 @@
 
 Kit 2.1+ is installed and updated by `rodo init` (the 2.0 scripts `rodo-install.cjs` and `rodo-update.cjs` are replaced by it). Do the steps for every version you skipped.
 
+## 2.2.1 → 2.3.0 (two plain project docs)
+
+What changes:
+- **New files.** `project/project-overview.md` (for a client, parts with ticks) and `project/how-it-works.md` (for a beginner). The writing rules are in the new skill file `project-docs.md`.
+- **Planner and coder.** The planner updates these files before work starts when a new feature or major change does not fit them; the coder makes them true and ticks the part when a card closes.
+- **`rodo validate`** warns `PROJECT_DOC_TOO_LONG` when one of them passes its word limit. It never blocks anything.
+- **`rodo init`** uses the project's own language when it adds missing files to an existing project.
+
+Steps: run `rodo init`. It adds the two files without touching existing ones. The next planner session fills them in. `RULES.md` is never replaced: compare it with the kit's new one (new section on the two docs). Commit: `git commit -am "chore: RODO kit 2.3.0"`.
+
 ## 2.1.0 → 2.2.0 (English templates, rodo new, safer sync)
 
 What changes:

package/dist/kit/agents-block.md

@@ -1,5 +1,5 @@
 <!-- rodo:start -->
-This repo uses the RODO method (kit 2.2.0). Before any work: read `.agents/skills/rodo/SKILL.md`,
+This repo uses the RODO method (kit 2.3.0). Before any work: read `.agents/skills/rodo/SKILL.md`,
 run `rodo sync`, then `rodo resume`. At the end of every session run `rodo sync`.
 RODO projects: see `rodo/*/project.json`. Never write secrets into rodo files. Never create boards.
 Never run `git pull`, `git fetch`, `git merge` or `git rebase`. If the repo is behind, tell the user once.

package/dist/kit/kit-manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "2.2.0",
+  "version": "2.3.0",
   "files": [
     {
       "src": ".agents/skills/rodo/SKILL.md",
@@ -21,6 +21,11 @@
       "dest": ".agents/skills/rodo/planner.md",
       "owner": "kit"
     },
+    {
+      "src": ".agents/skills/rodo/project-docs.md",
+      "dest": ".agents/skills/rodo/project-docs.md",
+      "owner": "kit"
+    },
     {
       "src": ".agents/skills/rodo/small-change.md",
       "dest": ".agents/skills/rodo/small-change.md",
@@ -89,9 +94,6 @@
     "CLAUDE.md": [
       "sha256:336cc4fbf19beaada7ccf9986414fa91851a8d7a07dfb3ccbe800a69eed0ab49"
     ],
-    ".agents/skills/rodo/SKILL.md": [
-      "sha256:a06382e130c46d0d7fc8ebfed4610a829496be1d0830ba79bf3135fa2da7b05b"
-    ],
     ".agents/skills/rodo/coder.md": [
       "sha256:6a5b3632e4c3b8065e8611fea5c267719bd9eddc797a7987723f78ef055e49b4"
     ],
@@ -101,18 +103,12 @@
     ".agents/skills/rodo/planner.md": [
       "sha256:36e6082c88920c2bf03f51e2e1a93f92cd2d06406d42a1cda357a65ca85f89e3"
     ],
+    ".agents/skills/rodo/SKILL.md": [
+      "sha256:a06382e130c46d0d7fc8ebfed4610a829496be1d0830ba79bf3135fa2da7b05b"
+    ],
     ".agents/skills/rodo/small-change.md": [
       "sha256:7bb7ceb277773e1ec4ed351ce0591e39dc5ba0911e0a32cce358ae16e2358c12"
     ],
-    ".agents/skills/rodo/templates/CHANGELOG.md": [
-      "sha256:74b575d434805ef245587bf704f0cda130d2cd0fb37e2499834853e0f372a059"
-    ],
-    ".agents/skills/rodo/templates/MAP.md": [
-      "sha256:9597d20bc5871cd5699f03e18b16356d06f212de37afe52ddfd3fd3f3e7ed200"
-    ],
-    ".agents/skills/rodo/templates/MEMORY.md": [
-      "sha256:68920278b000efa6b64cc206553720e14cb8af3a4154623e5babef3a745c0e03"
-    ],
     ".agents/skills/rodo/templates/acceptance.feature": [
       "sha256:0156ea9eb06f09de596a52a5ad2b1852b351d9cbe7a28230a4f90a2138a4b131"
     ],
@@ -125,12 +121,21 @@
     ".agents/skills/rodo/templates/card.rodo.md": [
       "sha256:6639b0b83bf25d8355f576b367e8fa10b51b0f5e7f100b5257c78cb4d3d0cc6a"
     ],
+    ".agents/skills/rodo/templates/CHANGELOG.md": [
+      "sha256:74b575d434805ef245587bf704f0cda130d2cd0fb37e2499834853e0f372a059"
+    ],
     ".agents/skills/rodo/templates/config.json": [
       "sha256:0c07d153aad92e647a8211a54cf696cfad5ac1445593383738da4cf29108f669"
     ],
     ".agents/skills/rodo/templates/glossary.md": [
       "sha256:0a5b2eff02a30ad5753547929789c8f3a6e39158ab65b433198e9845df42dfb6"
     ],
+    ".agents/skills/rodo/templates/MAP.md": [
+      "sha256:9597d20bc5871cd5699f03e18b16356d06f212de37afe52ddfd3fd3f3e7ed200"
+    ],
+    ".agents/skills/rodo/templates/MEMORY.md": [
+      "sha256:68920278b000efa6b64cc206553720e14cb8af3a4154623e5babef3a745c0e03"
+    ],
     ".agents/skills/rodo/templates/simple.md": [
       "sha256:b81908a8886698cce148400113a2525f6c44cf34c8e412290ba1652b3b928b6f"
     ],
@@ -181,6 +186,16 @@
       "src": "project-template/project/glossary.md",
       "dest": "project/glossary.md",
       "owner": "project"
+    },
+    {
+      "src": "project-template/project/how-it-works.md",
+      "dest": "project/how-it-works.md",
+      "owner": "project"
+    },
+    {
+      "src": "project-template/project/project-overview.md",
+      "dest": "project/project-overview.md",
+      "owner": "project"
     }
   ],
   "projectTemplateEn": [
@@ -223,6 +238,16 @@
       "src": "project-template-en/project/glossary.md",
       "dest": "project/glossary.md",
       "owner": "project"
+    },
+    {
+      "src": "project-template-en/project/how-it-works.md",
+      "dest": "project/how-it-works.md",
+      "owner": "project"
+    },
+    {
+      "src": "project-template-en/project/project-overview.md",
+      "dest": "project/project-overview.md",
+      "owner": "project"
     }
   ]
 }

package/dist/kit/project-template/RULES.md

@@ -1,4 +1,4 @@
-# روش RODO: راهنمای آدم‌ها (نسخهٔ کیت ۲.۲.۰)
+# روش RODO: راهنمای آدم‌ها (نسخهٔ کیت ۲.۳.۰)
 
 > این فایل برای شماست، نه برای AI. AI همین قواعد را از `.agents/skills/rodo/` می‌خواند.
 > اگر فقط ۲ دقیقه وقت دارید، «شروع سریع» و بخش ۱، ۳ و ۴ را بخوانید.
@@ -54,7 +54,9 @@ rodo/
     ├── project/
     │   ├── brief.md           پروژه به زبان ساده
     │   ├── architecture.md    بخش‌ها و فناوری‌ها، و چرا
-    │   └── glossary.md        واژه‌های پروژه و معنی‌شان
+    │   ├── glossary.md        واژه‌های پروژه و معنی‌شان
+    │   ├── project-overview.md  طرح کلی برای کارفرما: بخش‌ها با تیک انجام‌شده‌ها
+    │   └── how-it-works.md    هر بخش چطور کار می‌کند، به زبان ساده برای مبتدی
     ├── inbox/                 کارت‌هایی که در وب ساخته شده‌اند (در Git نیست)
     └── cycles/
         └── 002-discount-code/    یک کارت و سندهایش (هیچ‌وقت جابه‌جا نمی‌شود)
@@ -232,6 +234,12 @@ AI قبل از هر تغییر این سؤال را از خودش می‌پرس
 - سندهای کارهای تمام‌شده یا لغوشده هرگز بازنویسی نمی‌شوند؛ تصمیم تازه در کارت تازه و در `MEMORY.md` نوشته می‌شود.
 - RODO خودش چیزی را اجرا نمی‌کند؛ فقط می‌گوید کدام بررسی‌ها برای این کار مناسب است و ابزارهای خود پروژه آن‌ها را اجرا می‌کنند.
 
+## دو سند سادهٔ پروژه
+- `project-overview.md` طرح کلی برای کارفرماست: پروژه چیست، چه بخش‌هایی دارد و کنار بخش‌های تمام‌شده تیک خورده است.
+- `how-it-works.md` برای شماست: پروژه از چه ساخته شده، هر بخش چطور کار می‌کند و کجای کار را راحت می‌کند.
+- اگر قابلیت تازه یا تغییر بزرگ با این دو سند نخواند، AI پیش از شروع کار آن‌ها را به‌روز می‌کند و بخش تازه بدون تیک اضافه می‌شود. موقع بستن کارت، متن با واقعیت یکی و تیک زده می‌شود.
+- این دو سند هیچ‌وقت از یکی دو صفحه بیشتر نمی‌شوند. `rodo validate` اگر طولانی شوند هشدار می‌دهد.
+
 ---
 
 ## ۹. مثال کوتاه: فروشگاه گل مریم

package/dist/kit/project-template/project/how-it-works.md

@@ -0,0 +1,13 @@
+# {{نام پروژه}}: چطور کار می‌کند
+
+<!-- برای یک مبتدی. مثل یک متخصص باتجربه که به کارآموز توضیح می‌دهد. حداکثر ۹۰۰ کلمه. طول هر بخش به اهمیت آن بستگی دارد. قانون کامل: .agents/skills/rodo/project-docs.md -->
+
+## نمای کلی
+
+{{چند جمله: وقتی کاربر کاری می‌کند، درخواست از کدام بخش‌ها می‌گذرد و کدام بخش با کدام حرف می‌زند}}
+
+## {{نام بخش یا زیرساخت، مثلاً پایگاه داده}}
+
+**چیست و چطور کار می‌کند:** {{به زبان ساده، با یک مثال از همین پروژه}}
+
+**کجای کار را راحت می‌کند:** {{اگر این بخش نبود چه کاری سخت می‌شد}}

package/dist/kit/project-template/project/project-overview.md

@@ -0,0 +1,15 @@
+# {{نام پروژه}}: طرح کلی
+
+<!-- برای کارفرما. زبان ساده، بدون نام فناوری، حداکثر ۵۰۰ کلمه. تیک فقط وقتی زده می‌شود که آن بخش واقعاً تمام شده باشد. قانون کامل: .agents/skills/rodo/project-docs.md -->
+
+## این پروژه چیست
+
+{{دو یا سه جمله: این پروژه چیست، برای چه کسی است و چه مشکلی را حل می‌کند}}
+
+## هدف‌ها
+
+- {{چیزی که با تمام شدن پروژه به دست می‌آید}}
+
+## بخش‌های پروژه
+
+- [ ] **{{نام بخش}}**: {{دو یا سه جمله دربارهٔ اینکه این بخش برای کاربر چه کاری می‌کند}}

package/dist/kit/project-template-en/RULES.md

@@ -1,4 +1,4 @@
-# The RODO method: guide for people (kit 2.2.0)
+# The RODO method: guide for people (kit 2.3.0)
 
 > This file is for you, not for the AI. The AI reads the same rules from `.agents/skills/rodo/`.
 
@@ -38,7 +38,7 @@ rodo/
     ├── MEMORY.md              important decisions, one line each with "because"
     ├── CHANGELOG.md           small changes without a card, one line each
     ├── RULES.md               this file
-    ├── project/               brief, architecture, glossary (always current)
+    ├── project/               brief, architecture, glossary, project-overview, how-it-works (always current)
     └── cycles/NNN-slug/       one folder per card: card.rodo.md, simple.md, spec.md, design.md, acceptance.feature
 ```
 
@@ -63,7 +63,14 @@ For every new feature, change or improvement, and for every change to behaviour
 - With a board, card files live on the board and arrive through `rodo sync`; `rodo init` adds them to `.gitignore`.
 - `rodo sync` never loses your text: when the board wins a conflict, your file is saved in `rodo/<project>/.rodo/conflicts/`.
 
-## 7. Never
+## 7. The two plain project docs
+
+- `project-overview.md` is the plan for a client: what the project is, its parts, and a tick beside the finished ones.
+- `how-it-works.md` is for you: what the project is built from, how each part works and what it makes easier.
+- If a new feature or major change does not fit them, the AI updates them before work starts and a new part goes in unticked. When the card closes, the text is made true and the part is ticked.
+- They never grow past one or two pages; `rodo validate` warns if they do.
+
+## 8. Never
 
 - No secrets (passwords, keys, tokens) in any file under `rodo/`, in cards or in commit messages.
 - The AI never deletes files without your OK, never creates boards, and never answers decisions or ticks approvals.

package/dist/kit/project-template-en/project/how-it-works.md

@@ -0,0 +1,13 @@
+# {{name}}: how it works
+
+<!-- For a beginner. Written like an experienced engineer explaining to an intern. At most 900 words. Each part is as long as its importance needs. Full rules: .agents/skills/rodo/project-docs.md -->
+
+## The big picture
+
+{{a few sentences: when a user does something, which parts the request passes through and which part talks to which}}
+
+## {{part or infrastructure name, for example the database}}
+
+**What it is and how it works:** {{in plain words, with an example from this project}}
+
+**What it makes easier:** {{what would be hard without it}}

package/dist/kit/project-template-en/project/project-overview.md

@@ -0,0 +1,15 @@
+# {{name}}: overview
+
+<!-- For the client. Plain words, no technology names, at most 500 words. Tick a part only when it is really finished. Full rules: .agents/skills/rodo/project-docs.md -->
+
+## What this project is
+
+{{two or three sentences: what it is, who it is for and what problem it solves}}
+
+## Goals
+
+- {{what the project delivers when it is finished}}
+
+## Parts of the project
+
+- [ ] **{{part name}}**: {{two or three sentences on what this part does for the user}}

package/package.json

@@ -1,50 +1,50 @@
-{
-  "name": "rodo-spec",
-  "version": "2.2.0",
-  "description": "RODO method CLI \u2014 install the kit, manage cards, sync with the board",
-  "license": "MIT",
-  "type": "module",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/n3xus-ir/rodo-spec.git",
-    "directory": "packages/cli"
-  },
-  "homepage": "https://github.com/n3xus-ir/rodo-spec#readme",
-  "keywords": [
-    "rodo",
-    "rodo-spec",
-    "kanban",
-    "cli",
-    "spec",
-    "ai-agent"
-  ],
-  "bin": {
-    "rodo": "dist/index.js"
-  },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE"
-  ],
-  "engines": {
-    "node": ">=20"
-  },
-  "scripts": {
-    "build": "tsup",
-    "prepack": "pnpm run build",
-    "test": "vitest run",
-    "typecheck": "tsc --noEmit"
-  },
-  "devDependencies": {
-    "@rodo/card-format": "workspace:*",
-    "@rodo/protocol": "workspace:*",
-    "@rodo/rodo-kit": "workspace:*",
-    "@types/node": "^22.0.0",
-    "commander": "^12.1.0",
-    "picocolors": "^1.1.1",
-    "tsup": "^8.3.5",
-    "typescript": "^5.7.2",
-    "vitest": "^2.1.8",
-    "yaml": "^2.7.0"
-  }
-}
+{
+  "name": "rodo-spec",
+  "version": "2.3.0",
+  "description": "RODO method CLI — install the kit, manage cards, sync with the board",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/alishafiee1/rodo-spec.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/alishafiee1/rodo-spec#readme",
+  "keywords": [
+    "rodo",
+    "rodo-spec",
+    "kanban",
+    "cli",
+    "spec",
+    "ai-agent"
+  ],
+  "bin": {
+    "rodo": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsup",
+    "prepack": "pnpm run build",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@rodo/card-format": "workspace:*",
+    "@rodo/protocol": "workspace:*",
+    "@rodo/rodo-kit": "workspace:*",
+    "@types/node": "^22.0.0",
+    "commander": "^12.1.0",
+    "picocolors": "^1.1.1",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8",
+    "yaml": "^2.7.0"
+  }
+}