rodo-spec 2.2.0 → 2.2.1

package/README.md

@@ -23,22 +23,29 @@ When initialized within a repository, RODO organizes agent capabilities, project
 
 ```text
 .
+├── AGENTS.md                         # Pointer to the RODO skill for AI assistants
 ├── .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
+│       └── 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...
 ```
 
 ---
@@ -50,27 +57,33 @@ When initialized within a repository, RODO organizes agent capabilities, project
 - **Node.js**: `>= 20.0.0`
 - **npm**, **pnpm**, or **yarn**
 
-### Global Install via npm
+### 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/n3xus-ir/rodo-spec.git
+git clone https://github.com/alishafiee1/rodo-spec.git
 cd rodo-spec
-npm install
-npm run build
-npm link
+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.
+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
@@ -81,10 +94,10 @@ rodo init --method-only --project myapp --lang en
 ```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`.
+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 specifications meet the schema, invariants, and constraints:
+Check that your cards and cycle documents meet all format rules:
 ```bash
 rodo validate --strict
 ```
@@ -101,63 +114,83 @@ rodo test
 
 ### 6. Review cycle and workspace health
 ```bash
-rodo status
+rodo status --local
 rodo doctor
 ```
 
 ---
 
-## Commands Table
+## Connecting to a RODO Board (3 Ways)
 
-The CLI executable is `rodo`. Below is the complete reference of core commands:
+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.
 
-| 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. |
+### 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
 
-## Method-Only vs. Board Sync
+# 2b. Or bind directly by passing the board ID
+rodo init --project myapp --board <boardId>
+```
 
-RODO supports two operational modes:
+### 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.
 
-### 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.
+### Ongoing Synchronization
+Once connected, run `rodo sync` at the start and end of every work session:
+```bash
+rodo sync
+```
 
-### 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"
-    ```
+- **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, reusable packages:
+This repository is maintained as a monorepo consisting of modular 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.
+- **[`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`.
 
 ---
 
@@ -169,54 +202,85 @@ This project is licensed under the [MIT License](LICENSE).
 
 ## راهنمای سریع (فارسی)
 
-رودو (**RODO**) یک متدولوژی و جعبه‌ابزار استاندارد برای توسعه نرم‌افزار با همکاری برنامه‌نویسان و هوش مصنوعی است. رودو یک دروازه سخت‌گیرانه نیست، بلکه روشی ساختاریافته است تا تمام مراحل ایده، مشخصات فنی، معماری و آزمون‌ها در قالب فایل‌های ساده و شفاف Markdown ثبت، اعتبارسنجی و اجرا شوند.
+رودو (**RODO**) یک روش کار و جعبه‌ابزار خط فرمان (`rodo`) برای توسعهٔ ساختاریافتهٔ نرم‌افزار با همکاری انسان و هوش مصنوعی است. RODO یک دروازهٔ مسدودکننده نیست؛ هیچ ابزاری جلوی `commit` یا ادامهٔ کار را نمی‌گیرد، بلکه باعث می‌شود نقشهٔ پروژه (`MAP.md`)، تصمیم‌ها (`MEMORY.md`)، توضیح ساده (`simple.md`) و مشخصات فنی (`spec.md`) همیشه با کد هماهنگ بمانند.
 
 ### ۱. نصب
 
-برای استفاده از ابزار خط فرمان `rodo`، نسخه ۲۰ یا بالاتر Node.js را نصب کرده و دستور زیر را اجرا کنید:
+پیشنیاز: **Node.js نسخهٔ ۲۰ یا بالاتر**. برای نصب سراسری از طریق `npm`:
 
 ```bash
 npm i -g rodo-spec
 ```
 
-### ۲. شروع سریع بدون سرور (حالت محلی / Method-Only)
+### ۲. شروع سریع بدون سرور (حالت آفلاین / 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 (به ۳ روش)
 
-اگر تمایل دارید کارت‌ها و چرخه‌های کاری با سرور متمرکز هماهنگ شوند:
+هر زمان که بخواهید کارت‌های پروژه را روی برد وب 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` تغییر دهید.
-
-### ۴. ساخت کارت چرخه جدید و اعتبارسنجی
+> **نکته:** آدرس پیش‌فرض سرور `https://rodo.n3xus.ir` است. برای استفاده از سرور دیگر می‌توانید متغیر محیطی `RODO_SERVER` را تنظیم کنید یا فلگ `--server <url>` را بدهید.
 
-برای تعریف یک تسک یا قابلیت جدید:
+### ۴. دستورات پرکاربرد روزانه
 
 ```bash
-# ساخت کارت جدید با اسلاگ اختصاصی
-rodo new "پیاده‌سازی احراز هویت" --slug auth-feature
-
-# بررسی صحت فایل‌ها و عدم وجود خطای ساختاری
-rodo validate --strict
+# دریافت خلاصهٔ وضعیت و زمینهٔ کارت فعال برای دادن به دستیار هوش مصنوعی
+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.2.1",
   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",

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.2.1)
 
 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.
 
@@ -163,6 +163,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/KIT_VERSION

@@ -1 +1 @@
-2.2.0
+2.2.1

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.2.1). 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.2.1",
   "files": [
     {
       "src": ".agents/skills/rodo/SKILL.md",

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

@@ -1,4 +1,4 @@
-# روش RODO: راهنمای آدم‌ها (نسخهٔ کیت ۲.۲.۰)
+# روش RODO: راهنمای آدم‌ها (نسخهٔ کیت ۲.۲.۱)
 
 > این فایل برای شماست، نه برای AI. AI همین قواعد را از `.agents/skills/rodo/` می‌خواند.
 > اگر فقط ۲ دقیقه وقت دارید، «شروع سریع» و بخش ۱، ۳ و ۴ را بخوانید.

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.2.1)
 
 > This file is for you, not for the AI. The AI reads the same rules from `.agents/skills/rodo/`.
 

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "rodo-spec",
-  "version": "2.2.0",
-  "description": "RODO method CLI \u2014 install the kit, manage cards, sync with the board",
+  "version": "2.2.1",
+  "description": "RODO method CLI — 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",