feat(M2): Documentation flow, accuracy, consistency cleanup, and cross-platform shell portability

README.md

@@ -16,69 +16,36 @@ This repo is organized similarly to `obra/superpowers` and is designed to scale
 ```text
 ai-coding-skills/
 ├── README.md
-├── docs/
-│   ├── README.md
-│   ├── INSTALLER.md
-│   ├── CODEX.md
-│   ├── CLAUDE-CODE.md
-│   ├── CURSOR.md
-│   ├── OPENCODE.md
-│   ├── ATLASSIAN.md
-│   ├── CREATE-PLAN.md
-│   ├── DO-TASK.md
-│   ├── IMPLEMENT-PLAN.md
-│   ├── PI.md
-│   ├── PI-COMMON-REVIEWER.md
-│   ├── PI-RESEARCH.md
-│   ├── PI-SUPERPOWERS.md
-│   ├── TELEGRAM-NOTIFICATIONS.md
-│   └── WEB-AUTOMATION.md
+├── docs/                          — user-facing docs (see docs/README.md)
 ├── skills/
-│   ├── _template/
-│   │   └── SKILL.md
 │   ├── atlassian/
-│   │   ├── codex/
-│   │   ├── claude-code/
-│   │   ├── cursor/
-│   │   ├── opencode/
-│   │   ├── pi/
-│   │   └── shared/
+│   │   ├── codex/   claude-code/   cursor/   opencode/   pi/   shared/
 │   ├── create-plan/
-│   │   ├── codex/
-│   │   ├── claude-code/
-│   │   ├── opencode/
-│   │   ├── cursor/
-│   │   └── pi/
+│   │   ├── codex/   claude-code/   cursor/   opencode/   pi/
 │   ├── do-task/
-│   │   ├── codex/
-│   │   ├── claude-code/
-│   │   ├── opencode/
-│   │   ├── cursor/
-│   │   └── pi/
+│   │   ├── codex/   claude-code/   cursor/   opencode/   pi/
 │   ├── implement-plan/
-│   │   ├── codex/
-│   │   ├── claude-code/
-│   │   ├── opencode/
-│   │   ├── cursor/
-│   │   └── pi/
+│   │   ├── codex/   claude-code/   cursor/   opencode/   pi/
 │   ├── reviewer-runtime/
-│   │   ├── pi/
-│   │   └── tests/
+│   │   ├── pi/        — Pi-specific run-review.sh + notify-telegram.sh
+│   │   └── tests/     — reviewer-runtime smoke tests
 │   └── web-automation/
-│       ├── codex/
-│       ├── claude-code/
-│       ├── cursor/
-│       ├── opencode/
-│       └── pi/
-├── .codex/
-├── .claude-plugin/
-├── .opencode/
-│   └── plugins/
-├── commands/
-├── hooks/
-└── tests/
+│       ├── codex/   claude-code/   cursor/   opencode/   pi/
+├── pi-package/
+│   └── skills/                    — Pi-facing mirror synced by sync:pi
+├── scripts/
+│   ├── lib/                       — shared Node helpers + portable.sh
+│   └── tests/                     — Node.js unit tests
+├── package.json
+└── pnpm-workspace.yaml
 ```
 
+## Where to Read Next
+
+See **[docs/README.md](docs/README.md)** for the full documentation index with
+ordered reading flow, one-line summaries for every doc, and links to per-agent
+install guides, skill docs, Pi docs, Telegram setup, and development notes.
+
 ## Skills
 
 | Skill | Agent Variant | Purpose | Status | Docs |
@@ -150,9 +117,11 @@ node scripts/manage-skills.mjs --client pi --scope packageGlobal --pi-package --
 node scripts/manage-skills.mjs --client pi --scope packageLocal --pi-package --action install --yes
 ```
 
-The wizard detects Codex, Claude Code, Cursor, OpenCode, and Pi, previews operations, checks Superpowers dependencies for workflow skills, and prints a final operation report.
+The wizard detects Codex, Claude Code, Cursor, OpenCode, and Pi, previews operations, checks
+Superpowers dependencies for workflow skills, and prints a final operation report.
 
-`ai_plan/` is gitignored local planning state used by `create-plan` and `do-task`. The skill manager does not install, sync, or publish `ai_plan/` contents.
+`ai_plan/` is gitignored local planning state used by `create-plan` and `do-task`. The skill
+manager does not install, sync, or publish `ai_plan/` contents.
 
 ## Pi Package