mdrules 0.1.1 → 0.2.3

package/README.md

@@ -3,85 +3,231 @@
 [![CI](https://github.com/rafiqui1987/mdrules/actions/workflows/ci.yml/badge.svg)](https://github.com/rafiqui1987/mdrules/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-**mdrules** is a local, open-source editor for the Markdown that drives your project and your AI agents:
-`CLAUDE.md`, `AGENTS.md` and everything under `docs/`. Run `mdrules` in any repo and get a VS Code-style
-file tree with an Obsidian-style live preview: editable tables, Mermaid diagrams, KaTeX math, footnotes,
-images and checklists, plus a dashboard of phases and tasks from frontmatter, git changes and reusable
-rule presets. Files are saved exactly as written, never reformatted, so the AI always reads clean, plain
-Markdown. Docs can also be viewed and edited in your own language while the source stays in sync.
+**See and edit every Markdown file in your project in one place: no split screen, no raw syntax in the
+way.**
+
+Run `mdrules` in any repository and it opens all its `.md` files (`README.md`, `CLAUDE.md`, `AGENTS.md`,
+`docs/`…) in a single editor that is also the preview. Tables, Mermaid diagrams, checklists and math
+render as you type, and change in place. Files are saved exactly as written, never reformatted, so Git
+diffs stay clean and AI agents keep reading plain Markdown.
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="docs/assets/screenshot-dark.png">
-  <img alt="mdrules editor: file tree, a phase doc with checklists, an editable table, a Mermaid diagram and KaTeX math" src="docs/assets/screenshot-light.png">
+  <img alt="mdrules editor: file tree of a project using the mdrules method, a phase with its tasks, a comment thread like in Word and a Mermaid diagram" src="docs/assets/screenshot-light.png">
 </picture>
 
 ## Quick start
 
-Requires Node.js 20 or newer.
+Requires Node.js 20 or newer. From the root of any project (monorepos included):
 
 ```bash
-# from the root of any project (monorepos included)
-npx mdrules          # first run asks: main doc, docs/ structure, rules, languages
+npx mdrules
 ```
 
-Or install it globally:
+The very first time, mdrules asks how you want your projects set up:
 
-```bash
-npm install -g mdrules      # or: pnpm add -g mdrules
-mdrules                     # init if needed, then open the editor
-mdrules init                # re-run the setup
-mdrules serve               # open the editor without running init
-mdrules serve --port 5000 --no-open
-```
+- **With your answers** (default): answer once (main doc, how to plan the work, the language you
+  work in, rules…). They are saved in `~/.mdrules/defaults.json` and every new project is set up
+  with them, without questions. For a project that needs something else: `mdrules init --custom`.
+- **Ask in each project**: run `mdrules -D` the first time. Each project asks its own questions.
+
+Change your choice any time with `mdrules setup`. Then the editor opens at `http://localhost:4319`;
+it only listens on `127.0.0.1`.
+
+## What it does
 
-The editor opens at `http://localhost:4319` and only listens on `127.0.0.1`.
+### 1. Every Markdown file of the project, in one place
 
-## Features
+A file tree with every `.md` in the folder where you run it, folders first. Search, expand or collapse
+all, create files and folders inline, hide what you don't need (`.mdrulesignore`) and delete from the
+right-click menu. Resize the sidebar by dragging its edge, or hide it for more room.
 
-### Live preview editor
+### 2. Edit and view at the same time
 
-Markdown syntax hides where the cursor isn't and comes back where you edit, as in Obsidian.
+There is no "editor | preview" split. Markdown syntax is hidden everywhere except the line you are
+editing, as in Obsidian, so you read the document as it looks and still write plain Markdown.
+Undo, redo and **discard** (back to how the file was when you opened it) sit next to the breadcrumb.
 
-- **Tables**: rendered and editable in place. Right-click a header to insert or delete columns, any row
-  to insert or delete rows. Drag column borders to resize (view-only, stored per browser). Paste a
-  range from Excel or Google Sheets to get a Markdown table; a hint offers `Alt+H` to drop the header row.
-- **Diagrams and structure**: ` ```mermaid ` diagrams that follow the app theme, and ` ```tree ` blocks
-  for folder layouts.
-- **Math and footnotes**: `$inline$` and `$$display$$` math with KaTeX (prices like `$5` stay text),
-  `[^1]` footnotes as numbered superscripts with the note on hover.
-- **Images**: local paths resolve from the document's folder, as on GitHub, and remote URLs load directly.
-- **Code blocks**: fences are hidden and only the language label is shown; copying still gives the full
-  Markdown.
-- **Selection toolbar**: select text to copy it and turn it into bold, italic, strikethrough, code or a
+### 3. Formatting without remembering syntax
+
+- **`/` commands**: type `/` at the start of a line (or `Ctrl+Space` anywhere) for a menu of headings,
+  lists, checklists, tables, code blocks, diagrams, quotes, links and frontmatter.
+- **Selection toolbar**: select text to copy it or turn it into bold, italic, strikethrough, code or a
   link. Hover a button for its variants (`**`/`__`, `*`/`_`, `***`).
-- **Checklists**: click to tick. After `Enter` on a task, `Ctrl+Enter` checks the new one.
-- **Insert menu**: `/` at the start of a line opens a numbered, grouped menu with headings, lists,
-  tables, code, diagrams and frontmatter.
 
-### Workspace
+### 4. Diagrams, tables and lists that are easy to work with
+
+- **Mermaid diagrams** (flowcharts, sequences…) render in place and follow the light or dark theme.
+  ` ```tree ` blocks draw folder structures.
+- **Tables**: edit cells directly. Right-click to insert or delete rows and columns; drag borders to
+  resize columns (view only, the file is not changed).
+- **Tables from Excel or Google Sheets**: paste a range of cells and it becomes a Markdown table.
+  `Alt+H` toggles whether the first row is a header.
+- **Checklists**: click to tick. After `Enter` on a task, `Ctrl+Enter` ticks the new one.
+- And more: KaTeX math (`$x^2$`, `$$…$$`), footnotes on hover, local and remote images, code blocks with
+  only their language label showing.
+
+### 5. Work in your language
+
+Most AI agents, and most teams, work best with docs in English. If English isn't easy for you, you
+don't have to choose:
+
+- Run `mdrules translate` and pick a language to review the docs in: Spanish, French, Portuguese,
+  German or Italian, or **type any other** (Japanese, Dutch…). mdrules then shows **every doc in that
+  language**.
+- The menus are in English by default and don't depend on the docs' language: pick English, Spanish,
+  French, Portuguese, German or Italian in **Settings → General**.
+  Read the architecture, tick tasks, write notes and fix a rule, all in your language.
+- The files in the repository **stay in one source language** (English by default), so the agent and
+  the rest of the team keep reading one consistent version.
+- Your edits are kept as a translation until you ask the agent for `/mdrules sync`: it applies them
+  to the source file and refreshes every translation. The sidebar marks which docs are pending.
+
+Example: you open `docs/tasks/T-004-login.md` in Spanish, add an acceptance criterion and tick two
+others. After `/mdrules sync`, the English file has the new criterion and the ticks, and the agent
+works from it.
 
-- **File tree**: every `.md` in the project in a sidebar. Search, expand or collapse all, create, ignore
-  (`.mdrulesignore`) and delete from the right-click menu.
-- **Undo and redo** buttons appear in the sidebar once there is something to undo.
-- **Dashboard** of phases and docs from frontmatter (`type`, `status`, `phase`, `updated`) with task
-  progress.
-- **Changes**: git diff of your Markdown, grouped by folder.
-- **Rules**: reusable rule presets written into your main doc.
-- **Settings**: font, size, line spacing, side margin, line width, and line wrapping (wrap, or scroll
-  horizontally). Light and dark themes, following the system until you pick one.
+### 6. A method to plan and follow the work
 
-### Languages
+`mdrules init` offers the **mdrules method**, a way of organizing the project so that you and the
+agent always know what is being built, how, and what comes next:
 
-Each project has a source language (English by default) plus any translation languages: English, Spanish,
-French, Portuguese, German and Italian. Translations live in `.mdrules/i18n/` (git-ignored). You can view
-and edit docs in your language, and the AI applies your edits to the source with `/mdrules sync`. The UI
-is translated too.
+```tree
+CLAUDE.md                  # short: map, commands, how to start and close a session
+docs/
+  README.md                # how the method works
+  vision.md                # what the project is, for whom, what is out of scope
+  architecture/            # technology and design decisions, one file per topic
+  phases/01-foundations.md # a construction phase: goal, its tasks, definition of done
+  TASKS.md                 # index: in progress, blocked, pending, done
+  tasks/T-001-....md       # one file per task: goal, acceptance checklist, next step, log
+```
+
+```mermaid
+flowchart LR
+  V[Vision] --> A[Architecture] --> P[Phase] --> T[Tasks] --> W[Work] --> C[Close the session]
+  C -->|next step| W
+  C -->|phase done| P
+```
+
+- **The main doc stays short** and points to `docs/`. If `CLAUDE.md` or `AGENTS.md` already exist,
+  they are not rewritten: mdrules adds a "Workflow" section with the map and the session routine.
+- **Each fact lives in one place**: decisions in `architecture/`, progress in the task files.
+- **Sessions pick up where they stopped**: the agent looks for tasks `in-progress`, reads their "Next
+  step" and tells you where you left off. `/mdrules-new-task` creates a task in the right place, and
+  `/mdrules-close-session` logs what was done, the next step and the status.
+- **Monorepos**: each area (`apps/`, `services/`…) gets its own short `CLAUDE.md`, `docs/ARCHITECTURE.md`
+  and tasks with its own prefix (`APP-001`, `SVC-001`); the root `docs/` holds vision, phases and
+  cross-area tasks (`CORE-001`). The agent reads only the area it is working on.
+- **The Dashboard** shows each phase with its progress and tasks, and a board of what is in progress,
+  blocked and pending.
+
+**Prefer spec-driven development?** Pick one of these instead, and the Dashboard follows it too:
+
+| Option | What you get |
+|---|---|
+| **[OpenSpec](https://github.com/Fission-AI/OpenSpec)** | `openspec/` with specs and proposed changes; the dashboard shows each change and its tasks |
+| **[GitHub Spec Kit](https://github.com/github/spec-kit)** | a constitution and one folder per feature (spec → plan → tasks); the dashboard shows what each has |
+
+mdrules runs their official installer, which also adds their commands to your agent (`/opsx:*`,
+`/speckit-*`). If it can't (Spec Kit needs [uv](https://docs.astral.sh/uv/)), it creates a compatible
+structure with a guide on how to add them later. Projects that already use either are detected and
+shown as they are. Choose **None** and mdrules adds no structure or workflow at all.
+
+### 7. Proposals and comments: answer the AI with clicks
+
+When an answer would be long or has options to choose from (or when you ask for one), the agent writes
+a **proposal** instead of a long chat message: options with small ASCII or Mermaid diagrams, choices to
+tick, open questions, and the docs the decision will change. You answer in mdrules:
+
+```text
+ ┌ Proposal: Authentication ─────────────────────────────┐
+ │  Option A (recommended)                               │
+ │   Browser ──REST──▶ Gateway ──gRPC──▶ Users ──▶ (DB)  │
+ │                                                       │
+ │  Your choice                                          │
+ │   (•) A: gateway validates                            │
+ │   ( ) B: each service validates                       │
+ │                                                       │
+ │  [ Done, send my answer ]                             │
+ └───────────────────────────────────────────────────────┘
+```
 
-## AI side
+- **Tick options**: a list marked `<!-- choose: one -->` behaves like radio buttons; any other
+  checklist allows several.
+- **Comment like in Word**: select text and press 💬. The text is highlighted and the thread shows next
+  to it, with replies and a button to resolve it. In the file, a comment is an HTML comment, invisible
+  on GitHub and readable by the agent:
 
-`mdrules init` installs `.claude/skills/mdrules/SKILL.md` with the project's Markdown conventions and the
-sync procedure. It also writes the selected working rules into the main doc, between
-`<!-- mdrules:rules:start -->` and `<!-- mdrules:rules:end -->`.
+  ```md
+  - [x] A: gateway validates
+    <!-- comment by Ana, 2026-10-22, on "gateway validates": What if it goes down? -->
+    <!-- reply by AI, 2026-10-22: Two instances minimum; added to the architecture. -->
+  ```
+
+- **Send your answer**: the button marks the proposal as answered and copies a message to paste in your
+  AI chat. The agent replies to your comments and updates every doc that depends on the decision
+  (tasks, phases, architecture…). A proposal is temporary: once applied, it is deleted and the decision
+  lives in those docs.
+- In big projects, proposals can be organized **by topic and area** (`docs/proposals/auth/…`,
+  `services/docs/proposals/…`) instead of one folder.
+
+It comes with the mdrules method, and can be turned on or off for any project in **Settings**.
+
+### 8. Your AI agent's skills
+
+The **Skills** tab lists every global skill you have for Claude Code, Codex, Gemini, Copilot or Cursor
+([Agent Skills](https://agentskills.io) format). Tag them to group them, expand one to read or edit its
+`SKILL.md`, see problems that would stop an agent from loading it, and **add it to the current project**
+(`.claude/skills/` and/or `.agents/skills/`). Tags are stored in `~/.mdrules/skills.json`, never in the
+skill.
+
+### 9. Also included
+
+- **Changes**: Git diff of your Markdown, grouped by folder and section.
+- **Rules**: reusable rule presets (e.g. "ask before committing") written into `CLAUDE.md` or `AGENTS.md`.
+- **Settings**, by section: General (interface language, theme), Editor (font, size, line spacing,
+  margins, line width, wrapping), Document languages and Proposals.
+
+## Keyboard shortcuts
+
+| Keys | Action |
+|---|---|
+| `/` at the start of a line, `Ctrl+Space` | Insert menu |
+| `Ctrl+Enter` | Tick or untick the task on the current line |
+| `Alt+H` | After pasting a table from a spreadsheet: toggle the header row |
+| `Ctrl+Z` / `Ctrl+Y` | Undo / redo |
+| `Ctrl+F` / `Ctrl+H` | Find / find and replace (box at the top right) |
+| `Enter` / `Shift+Enter` | Next / previous match |
+| `Alt+C` / `Alt+W` / `Alt+R` | Match case / whole word / regular expression |
+| `Escape` | Close a menu or the selection toolbar |
+
+## Commands
+
+```bash
+mdrules                     # set up the project if needed, then open the editor
+mdrules init                # run the setup again (with your defaults, if you saved them)
+mdrules init --custom       # set up this project with its own answers
+mdrules setup               # change your defaults, or switch to asking in each project
+mdrules -D                  # first run: don't save defaults, ask in each project
+mdrules serve               # open the editor without the setup
+mdrules serve --port 5000 --no-open
+mdrules translate           # choose languages to review the docs in (also: mdrules --translate)
+```
+
+To keep it installed: `npm install -g mdrules` (or `pnpm add -g mdrules`).
+
+## For AI agents
+
+`mdrules init` installs `.claude/skills/mdrules/SKILL.md`, which tells the agent how to write Markdown
+that mdrules presents well and how to keep translations in sync. It also writes into the main doc:
+
+- the working rules you picked, between `<!-- mdrules:rules:start -->` and `<!-- mdrules:rules:end -->`;
+- how the project plans its work (the mdrules method, OpenSpec or Spec Kit), between
+  `<!-- mdrules:workflow:start -->` and `<!-- mdrules:workflow:end -->`. With the mdrules method it
+  also installs the `mdrules-new-task` and `mdrules-close-session` skills.
+- with proposals on, how the agent writes proposals and answers comments (skill
+  `mdrules-proposals`), between `<!-- mdrules:proposals:start -->` and `<!-- mdrules:proposals:end -->`.
 
 ```bash
 mdrules sync --status [--json]                   # translations + files not in the source language
@@ -89,6 +235,16 @@ mdrules sync --mark [--lang xx] <path...>|--all  # record translations as in syn
 mdrules sync --keep <path...>                    # keep files in their current language
 ```
 
+## Uninstall
+
+```bash
+npm uninstall -g mdrules    # or: pnpm remove -g mdrules (use the one you installed it with)
+```
+
+To remove it from a project, delete `.mdrules/` and `.claude/skills/mdrules*/`, the `.mdrules/` line in
+`.gitignore`, and the `mdrules:rules`, `mdrules:workflow` and `mdrules:proposals` blocks in your main doc (keep the text
+inside if you still want it). Editor settings, rule presets and skill tags live in `~/.mdrules`.
+
 ## Development
 
 ```bash