rbin-task-flow 1.24.0 → 1.25.1

package/.claude/skills/rbin-coding-standards/SKILL.md

@@ -13,9 +13,10 @@ paths: ["src/**", "app/**"]
 
 1. Apply the **checklist** in `.cursor/rules/coding_standards.mdc` (default for all implementation). Do **not** read the entire `.mdc` or full markdown into context if the checklist already covers the task.
 2. Implement using checklist rules: `app/` thin, `features/`, `shared/`, service+use-case, RHF+zod+`Controller`, `cn()`, no `any`, no raw base UI.
-3. **Only if ambiguous** (Nest gateways, DataHandler, route groups, naming edge case): open **one or two sections** of `.task-flow/docs/coding-standards-full.md` — never paste or load the whole file.
-4. If `graphify-out/graph.json` exists, `graphify query` before choosing file paths for new code.
-5. No explanatory code comments; use `dev-logs/` for non-obvious design notes.
+3. **Vercel projects:** env files per **Vercel — environment variables** in `coding-standards-full.md` (§0–§8).
+4. **Only if ambiguous** (Nest gateways, DataHandler, route groups, naming edge case): open **one or two sections** of `.task-flow/guides/coding-standards-full.md` — never paste or load the whole file.
+5. If `graphify-out/graph.json` exists, `graphify query` before choosing file paths for new code.
+6. No explanatory code comments; use `dev-logs/` for non-obvious design notes.
 
 ## Token discipline
 

package/.claude/skills/rbin-coding-standards/reference.md

@@ -5,7 +5,8 @@
 | Doc | Path | When |
 |-----|------|------|
 | **Checklist** (default) | `.cursor/rules/coding_standards.mdc` | Every implementation; glob on `src/**`, `app/**` in Cursor |
-| **Full reference** (sections only) | `.task-flow/docs/coding-standards-full.md` | Nest/Prisma detail, long examples, ESLint table, DataHandler, providers |
+| **Full reference** (sections only) | `.task-flow/guides/coding-standards-full.md` | Nest/Prisma detail, long examples, ESLint table, DataHandler, providers |
+| **Vercel `.env`** | `coding-standards-full.md` § Vercel | Projects on Vercel — 3 mirrored env files + sync scripts |
 
 ## Checklist essentials
 
@@ -40,3 +41,4 @@
 | Context / Auth Hook | Auth provider pattern |
 | Testing | E2E placement |
 | Critical Rules | Final verification |
+| Vercel — environment variables | `.env` setup on Vercel deploys → open this section in full doc |

package/.claude/skills/task-flow-audit/SKILL.md

@@ -7,7 +7,7 @@ disable-model-invocation: true
 # Task Flow — Audit
 
 1. Scan project structure and `package.json`.
-2. Score categories vs `.cursor/rules/coding_standards.mdc` checklist (Full / Partial / Missing). Use `.task-flow/docs/coding-standards-full.md` only for deep dives — not the whole file.
+2. Score categories vs `.cursor/rules/coding_standards.mdc` checklist (Full / Partial / Missing). Use `.task-flow/guides/coding-standards-full.md` only for deep dives — not the whole file.
 3. Present table and incremental improvement options.
 4. **Ask** user what to adopt; never impose refactors.
 5. Generate task lines for selected items only if user confirms.

package/.claude/skills/task-flow-improve-changes/SKILL.md

@@ -8,7 +8,7 @@ disable-model-invocation: true
 
 1. Run `git diff --name-only HEAD` (read-only git).
 2. If empty, stop — no uncommitted changes.
-3. Audit **only** those paths using the same checklist as audit (`.cursor/rules/coding_standards.mdc`). Full reference: `.task-flow/docs/coding-standards-full.md` — relevant sections only if a category needs depth.
+3. Audit **only** those paths using the same checklist as audit (`.cursor/rules/coding_standards.mdc`). Full reference: `.task-flow/guides/coding-standards-full.md` — relevant sections only if a category needs depth.
 4. Present findings; ask what to fix.
 5. Does **not** run lint/build — use `/task-flow-check` separately.
 

package/.claude/skills/task-flow-report/SKILL.md

@@ -9,7 +9,7 @@ paths: [".task-flow/**"]
 
 1. Verify task X is fully `done` in `status.json` (warn if partial).
 2. Read `tasks.json`; analyze related code changes (read-only git ok).
-3. Write `.task-flow/docs/task-X-implementation.md` using project template.
-4. Create `.task-flow/docs/` if missing.
+3. Write `.task-flow/guides/reports/task-X-implementation.md` using project template.
+4. Create `.task-flow/guides/reports/` if missing.
 
 Reference: `.cursor/rules/task_report.mdc`

package/.claude/skills/task-flow-sync/SKILL.md

@@ -12,7 +12,7 @@ paths: [".task-flow/**"]
 1. Read `.task-flow/tasks.input.txt` (only lines starting with `- `).
 2. Read `.task-flow/.internal/tasks.json` and `status.json` if they exist.
 3. Compare by `originalRequest`: new, removed, modified, unchanged tasks.
-4. **New:** generate subtasks (3–8 each), add pending status, update `tasks.status.md`. Subtask instructions: follow **checklist** in `.cursor/rules/coding_standards.mdc` only — not `.task-flow/docs/coding-standards-full.md`.
+4. **New:** generate subtasks (3–8 each), add pending status, update `tasks.status.md`. Subtask instructions: follow **checklist** in `.cursor/rules/coding_standards.mdc` only — not `.task-flow/guides/coding-standards-full.md`.
 5. **Removed:** delete from all three stores.
 6. **Modified:** update title/description, regenerate subtasks, **preserve** done/pending status where possible.
 7. **Unchanged:** leave task data and status as-is.

package/.cursor/rules/coding_standards.mdc

@@ -6,7 +6,7 @@ alwaysApply: false
 
 # Coding Standards — Checklist
 
-Apply when implementing Task Flow subtasks or feature code (this file is the **checklist**). For workflows and section index: invoke `@rbin-coding-standards` (`disable-model-invocation: true` — not auto). **Full guide:** [.task-flow/docs/coding-standards-full.md](mdc:.task-flow/docs/coding-standards-full.md) — **sections only**; never paste entire file into chat.
+Apply when implementing Task Flow subtasks or feature code (this file is the **checklist**). For workflows and section index: invoke `@rbin-coding-standards` (`disable-model-invocation: true` — not auto). **Full guide:** [.task-flow/guides/coding-standards-full.md](mdc:.task-flow/guides/coding-standards-full.md) — **sections only**; never paste entire file into chat.
 
 ---
 
@@ -84,9 +84,21 @@ src/
 
 ---
 
+## Vercel — `.env` (when project deploys on Vercel)
+
+Follow **Vercel — environment variables** in [coding-standards-full.md](mdc:.task-flow/guides/coding-standards-full.md) (§0–§8):
+
+- **3 mirrored files:** `.env.example` (committed, empty values), `.env.local` (dev), `.env.production` (synced to Vercel).
+- Same keys, **alphabetical order**, one var per line — no section comments breaking alignment.
+- `.gitignore`: `.env`, `.env.*`, `!.env.example`.
+- Scripts: `scripts/env-files-check.sh`, `scripts/vercel-env-sync.sh` (full content in full doc §5–§6).
+- Audit orphan vars before aligning; classify `NEXT_PUBLIC_*`/flags as plaintext, rest as secret on Vercel.
+
+---
+
 ## Audit / sync
 
-- **`task-flow: audit`:** score against this checklist; open [coding-standards-full.md](mdc:.task-flow/docs/coding-standards-full.md) only for deep dives or user-requested depth.
+- **`task-flow: audit`:** score against this checklist; open [coding-standards-full.md](mdc:.task-flow/guides/coding-standards-full.md) only for deep dives or user-requested depth.
 - **`task-flow: sync`:** subtask instructions follow checklist patterns (structure, naming, service+use-case) — not full doc.
 
 ---
@@ -97,4 +109,5 @@ src/
 |------|-----|
 | Implementing code | `@rbin-coding-standards` |
 | Full examples / Nest / gateways | Sections of `coding-standards-full.md` |
+| Vercel `.env` setup | `coding-standards-full.md` § Vercel |
 | Audit all categories | `@task-flow-audit` |

package/.cursor/rules/graphify-task-flow.mdc

@@ -12,7 +12,7 @@ alwaysApply: false
   - **`task-flow: think`:** Optional `graphify query` for gap analysis on large repos.
   - **`task-flow: review X`:** Optional `graphify affected "<symbol>"` to verify impact surface.
   - **`task-flow: validate`:** Optional `graphify query` per task area before verifying implementation; then append lacunas + sync per `task_validate.mdc`.
-  - **`task-flow: audit`:** Graphify is structural only; scoring uses [coding_standards.mdc](mdc:.cursor/rules/coding_standards.mdc) checklist. Deep dive: sections of [coding-standards-full.md](mdc:.task-flow/docs/coding-standards-full.md) only if user asks for depth.
+  - **`task-flow: audit`:** Graphify is structural only; scoring uses [coding_standards.mdc](mdc:.cursor/rules/coding_standards.mdc) checklist. Deep dive: sections of [coding-standards-full.md](mdc:.task-flow/guides/coding-standards-full.md) only if user asks for depth.
 
 - **When NOT to use Graphify:**
   - `task-flow: sync`, `status`, `estimate`, `report`, `generate flow` — only `.task-flow/` files.
@@ -26,7 +26,7 @@ alwaysApply: false
 - **CLI (project root):**
   - Build graph: `graphify extract . --backend claude-cli` or `rbin-task-flow init --graphify` (re-run after large refactors).
   - Query: `graphify query "question"` · `graphify affected "node"`.
-  - Guide: [.task-flow/GRAPHIFY.md](mdc:.task-flow/GRAPHIFY.md)
+  - Guide: [.task-flow/guides/GRAPHIFY.md](mdc:.task-flow/guides/GRAPHIFY.md)
 
 - **Principle:**
   > **Task Flow decides what to do; Graphify helps find where in the code — only during implementation and exploration commands.**

package/.cursor/rules/task-flow-cursor.mdc

@@ -14,6 +14,7 @@ alwaysApply: true
 | `.task-flow/.internal/tasks.json` | Definitions |
 | `.task-flow/.internal/status.json` | Status source of truth |
 | `.task-flow/contexts/` | Specs / mockups |
+| `.task-flow/guides/` | Platform guides, Graphify, standards, reports |
 
 ## Prefer skills (`.cursor/skills/`)
 
@@ -43,10 +44,10 @@ Never write git — user runs all commits. Policy: [rbin-git-policy.mdc](mdc:.cu
 
 ## Graphify (optional)
 
-On `run` / `think`, if `graphify-out/` exists: `graphify query` before repo-wide grep. Rule: `graphify-task-flow`. Guide: `.task-flow/GRAPHIFY.md`.
+On `run` / `think`, if `graphify-out/` exists: `graphify query` before repo-wide grep. Rule: `graphify-task-flow`. Guide: `.task-flow/guides/GRAPHIFY.md`.
 
 ## More detail
 
-- Workflows: `.task-flow/CURSOR.md`
-- Full guide: `.task-flow/platforms/cursor.md`
-- Codex parity: `.task-flow/CODEX.md`
+- Workflows: `.task-flow/guides/CURSOR.md`
+- Full guide: `.task-flow/guides/platforms/cursor.md`
+- Codex parity: `.task-flow/guides/CODEX.md`

package/.cursor/rules/task-flow-sync.mdc

@@ -30,7 +30,7 @@ Task IDs stay sequential (1, 2, 3…) matching `tasks.input.txt` order.
 - `originalRequest`: exact input line; `createdAt`: ISO 8601 for new tasks
 - 3–8 subtasks: title, description, instructions (3–5 steps)
 - Contexts: keyword match or `task-flow-screen file.ext` → `.task-flow/contexts/file.ext`
-- Subtask instructions: **checklist** in [coding_standards.mdc](mdc:.cursor/rules/coding_standards.mdc) only — not [coding-standards-full.md](mdc:.task-flow/docs/coding-standards-full.md)
+- Subtask instructions: **checklist** in [coding_standards.mdc](mdc:.cursor/rules/coding_standards.mdc) only — not [coding-standards-full.md](mdc:.task-flow/guides/coding-standards-full.md)
 - More templates: [task_generation.mdc](mdc:.cursor/rules/task_generation.mdc)
 
 **Sync rules:** no codebase exploration; no questions; do not fill `tasks.flow.md` (only `generate flow`).

package/.cursor/rules/task_analysis.mdc

@@ -35,7 +35,7 @@ User says `task-flow: think`, `suggest tasks`, `check for new tasks`, `analyze c
 
 ## Optional roadmap
 
-For package improvements see [.task-flow/OPTIMIZATION-PLAN.md](mdc:.task-flow/OPTIMIZATION-PLAN.md) — not part of think unless user asks.
+For package improvements see [.task-flow/guides/OPTIMIZATION-PLAN.md](mdc:.task-flow/guides/OPTIMIZATION-PLAN.md) — not part of think unless user asks.
 
 ## Integration
 

package/.cursor/rules/task_audit.mdc

@@ -5,7 +5,7 @@ alwaysApply: false
 
 # task-flow: audit
 
-When the user runs `task-flow: audit`, perform a non-destructive analysis against the **checklist** in [coding_standards.mdc](mdc:.cursor/rules/coding_standards.mdc). For deep architecture or examples, read only relevant sections of [coding-standards-full.md](mdc:.task-flow/docs/coding-standards-full.md) — do not load the entire file unless the user asks for depth.
+When the user runs `task-flow: audit`, perform a non-destructive analysis against the **checklist** in [coding_standards.mdc](mdc:.cursor/rules/coding_standards.mdc). For deep architecture or examples, read only relevant sections of [coding-standards-full.md](mdc:.task-flow/guides/coding-standards-full.md) — do not load the entire file unless the user asks for depth.
 
 ---
 
@@ -36,7 +36,7 @@ Scan the codebase to understand:
 
 ### Step 2 — Score each category
 
-Score using the **checklist** in [coding_standards.mdc](mdc:.cursor/rules/coding_standards.mdc). For a category that needs examples (Nest gateways, DataHandler, long patterns), read **one section** of [coding-standards-full.md](mdc:.task-flow/docs/coding-standards-full.md) — not the whole file unless the user requests depth.
+Score using the **checklist** in [coding_standards.mdc](mdc:.cursor/rules/coding_standards.mdc). For a category that needs examples (Nest gateways, DataHandler, long patterns), read **one section** of [coding-standards-full.md](mdc:.task-flow/guides/coding-standards-full.md) — not the whole file unless the user requests depth.
 
 For each category below, rate adherence: **Full / Partial / Missing**
 

package/.cursor/rules/task_improve_changes.mdc

@@ -7,7 +7,7 @@ alwaysApply: false
 
 When the user runs `task-flow: improve changes`:
 
-1. **Audit current changes only**: Do the **same as** [task-flow: audit](mdc:.cursor/rules/task_audit.mdc) (score against the [coding_standards.mdc](mdc:.cursor/rules/coding_standards.mdc) checklist; [full doc](mdc:.task-flow/docs/coding-standards-full.md) only if needed), but **restricted to files that were changed and not yet committed**.
+1. **Audit current changes only**: Do the **same as** [task-flow: audit](mdc:.cursor/rules/task_audit.mdc) (score against the [coding_standards.mdc](mdc:.cursor/rules/coding_standards.mdc) checklist; [full doc](mdc:.task-flow/guides/coding-standards-full.md) only if needed), but **restricted to files that were changed and not yet committed**.
 2. **Do not run project checks here**: Lint fix and build now belong to [task-flow: check](mdc:.cursor/rules/task_check.mdc).
 
 ---

package/.cursor/rules/task_report.mdc

@@ -12,7 +12,7 @@ alwaysApply: false
     - **READ**: `.task-flow/.internal/status.json` to verify task is completed
     - **ANALYZE**: Codebase changes related to the task (git history, file changes)
     - **GENERATE**: Markdown report documenting what was implemented
-    - **SAVE**: Report to `.task-flow/docs/task-X-implementation.md`
+    - **SAVE**: Report to `.task-flow/guides/reports/task-X-implementation.md`
 
 - **Report Generation Rules:**
   1. **Verify Completion**: Task must be marked as "done" in status.json (all subtasks completed)
@@ -23,9 +23,9 @@ alwaysApply: false
      - Code changes summary
      - Testing information (if applicable)
      - Notes and considerations
-  3. **File Location**: `.task-flow/docs/task-X-implementation.md`
+  3. **File Location**: `.task-flow/guides/reports/task-X-implementation.md`
   4. **File Naming**: `task-{taskId}-implementation.md` (e.g., `task-1-implementation.md`)
-  5. **Directory Creation**: Create `.task-flow/docs/` if it doesn't exist
+  5. **Directory Creation**: Create `.task-flow/guides/reports/` if it doesn't exist
 
 - **Report Template:**
   ```markdown
@@ -93,7 +93,7 @@ alwaysApply: false
   2. Verify task 1 is completed
   3. Analyze codebase for changes related to task 1
   4. Generate markdown report
-  5. Save to .task-flow/docs/task-1-implementation.md
+  5. Save to .task-flow/guides/reports/task-1-implementation.md
   6. Show confirmation message
   ```
 
@@ -105,7 +105,7 @@ alwaysApply: false
 - **Integration:**
   - Works with [task-flow-cursor.mdc](mdc:.cursor/rules/task-flow-cursor.mdc) / `@task-flow-report`
   - Uses task data from `.task-flow/.internal/tasks.json` and `.task-flow/.internal/status.json`
-  - Reports are stored in `.task-flow/docs/` directory
+  - Reports are stored in `.task-flow/guides/reports/` directory
   - Can reference git history for implementation details
 
 - **Principle:**

package/.task-flow/README.md

@@ -1,19 +1,37 @@
 # RBIN Task Flow - Quick Commands
 
+## Layout
+
+```text
+.task-flow/
+├── README.md              ← você está aqui
+├── tasks.input.txt        ← defina tasks (`- descrição`)
+├── tasks.status.md        ← progresso (auto; não editar)
+├── tasks.flow.md          ← deps/horas (task-flow: generate flow)
+├── contexts/              ← specs, mockups
+├── .internal/             ← tasks.json, status.json (sistema)
+└── guides/                ← documentação e configs
+    ├── AI-PLATFORMS.md
+    ├── GRAPHIFY.md
+    ├── CODEX.md · CURSOR.md
+    ├── coding-standards-full.md  ← inclui padrão .env Vercel (§ Vercel)
+    ├── platforms/         ← Claude, Cursor, Codex
+    └── reports/           ← task-X-implementation.md
+```
+
 **Optimize by AI platform:**
 
 | Platform | Guide |
 |----------|--------|
-| Index | [AI-PLATFORMS.md](AI-PLATFORMS.md) |
-| Claude Code | [platforms/claude-code.md](platforms/claude-code.md) |
-| Cursor | [platforms/cursor.md](platforms/cursor.md) |
-| Codex | [platforms/codex.md](platforms/codex.md) |
-| Graphify + Task Flow | [GRAPHIFY.md](GRAPHIFY.md) |
-| Codex | [CODEX.md](CODEX.md) · [platforms/codex.md](platforms/codex.md) |
-| Cursor | [CURSOR.md](CURSOR.md) · [platforms/cursor.md](platforms/cursor.md) |
-| Otimização (tokens / roadmap) | [OPTIMIZATION-PLAN.md](OPTIMIZATION-PLAN.md) |
-| Subtarefas para implementar otimização | [OPTIMIZATION-IMPLEMENTATION-TASKS.md](OPTIMIZATION-IMPLEMENTATION-TASKS.md) |
-| Coding standards (full, on demand) | [docs/coding-standards-full.md](docs/coding-standards-full.md) |
+| Index | [guides/AI-PLATFORMS.md](guides/AI-PLATFORMS.md) |
+| Claude Code | [guides/platforms/claude-code.md](guides/platforms/claude-code.md) |
+| Cursor | [guides/platforms/cursor.md](guides/platforms/cursor.md) |
+| Codex | [guides/platforms/codex.md](guides/platforms/codex.md) |
+| Graphify + Task Flow | [guides/GRAPHIFY.md](guides/GRAPHIFY.md) |
+| Codex workflows | [guides/CODEX.md](guides/CODEX.md) |
+| Cursor quick ref | [guides/CURSOR.md](guides/CURSOR.md) |
+| Otimização (tokens) | [guides/OPTIMIZATION-PLAN.md](guides/OPTIMIZATION-PLAN.md) |
+| Coding standards (full) | [guides/coding-standards-full.md](guides/coding-standards-full.md) (Vercel `.env` no topo) |
 
 ## 🚀 Quick Commands
 
@@ -21,13 +39,13 @@
 |---------|-------------|
 | `task-flow: sync` | Complete synchronization: adds new, removes deleted, updates modified, preserves status |
 | `task-flow: think` | Analyzes code and suggests new tasks |
+| `task-flow: validate` | Deep audit vs codebase; revert false done; append gaps to `tasks.input.txt`; sync |
 | `task-flow: status` | Shows current task status |
 | `task-flow: run next X` | Works on next X subtasks (e.g., `task-flow: run next 4`) |
 | `task-flow: run X` | Executes all pending subtasks of task X (e.g., `task-flow: run 1`) |
 | `task-flow: run X,Y` | Executes multiple tasks (e.g., `task-flow: run 10,11`) |
 | `task-flow: run all` | Executes all tasks |
 | `task-flow: review X` | Reviews specific task(s) (e.g., `task-flow: review 1` or `task-flow: review 10,11` or `task-flow: review all`) |
-| `task-flow: validate` | Deep-validates tasks vs codebase, reverts false done, appends gaps to `tasks.input.txt`, syncs (default: all) |
 | `task-flow: refactor X` | Refactors specific task(s) (e.g., `task-flow: refactor 1` or `task-flow: refactor 10,11` or `task-flow: refactor all`) |
 | `task-flow: estimate X` | Estimates time for task X (e.g., `task-flow: estimate 1` or `task-flow: estimate 10,11`) |
 | `task-flow: report X` | Generates implementation report for task X (e.g., `task-flow: report 1` or `task-flow: report 10,11`) |
@@ -54,11 +72,14 @@ Complete synchronization between `tasks.input.txt` and the system:
 ### `task-flow: think`
 Analyzes code and suggests new tasks. Asks before adding to `tasks.input.txt`.
 
+### `task-flow: validate`
+Deep validation: checks subtasks against the codebase, reverts false `done`, appends lacunas to `tasks.input.txt`, and syncs. Invoke: `@task-flow-validate` / `/task-flow-validate`.
+
 ### `task-flow: status`
 Shows current status of tasks and subtasks from the `tasks.status.md` file.
 
 ### `task-flow: audit`
-Audits the **entire codebase** against the **checklist** in [coding_standards.mdc](.cursor/rules/coding_standards.mdc). Deep reference: [docs/coding-standards-full.md](docs/coding-standards-full.md) (sections only, on demand). Non-destructive: reports gaps and suggests incremental improvements; the user chooses what to adopt. See [task_audit.mdc](.cursor/rules/task_audit.mdc) for the full flow.
+Audits the **entire codebase** against the **checklist** in [coding_standards.mdc](../.cursor/rules/coding_standards.mdc). Deep reference: [guides/coding-standards-full.md](guides/coding-standards-full.md) (sections only, on demand). Non-destructive: reports gaps and suggests incremental improvements; the user chooses what to adopt. See [task_audit.mdc](../.cursor/rules/task_audit.mdc) for the full flow.
 
 ### `task-flow: check`
 Runs **lint fix** and **build** for the project. Check `package.json` for a lint-with-fix script (e.g. `lint:fix`, `lint -- --fix`) and a build script; run lint fix first, fix any warnings or errors, then run build and fix until it passes. Use before committing or before `task-flow: improve changes` to ensure the project is clean.
@@ -102,16 +123,6 @@ Reviews specific task(s) marked as "done" to verify they are actually completed.
 - `task-flow: review 10,11` → Reviews tasks 10 and 11
 - `task-flow: review all` → Reviews all tasks
 
-### `task-flow: validate`
-Deep validation: checks all subtasks (done and pending) against the codebase, reverts falsely marked `done`, discovers lacunas (missing tests, TODOs, incomplete work), **appends** them to `tasks.input.txt`, and runs sync. Unlike `think` (asks before add) or `review` (done only, asks before revert).
-
-**Examples:**
-- `task-flow: validate` → Validates all tasks
-- `task-flow: validate 1` → Validates task 1 only
-- `task-flow: validate 2,3` → Validates tasks 2 and 3
-
-**Invoke:** `@task-flow-validate` (Cursor) · `/task-flow-validate` (Claude)
-
 ### `task-flow: refactor X`
 Refactors code from specific task(s). Removes explanatory comments, improves code without changing functionality.
 
@@ -139,25 +150,8 @@ Populates `tasks.flow.md` with: (1) task dependencies (for parallelization), (2)
 ### `task-flow: report X` (simplified syntax)
 Generates a detailed implementation report for completed task(s) in Markdown format.
 
-**Report includes:**
-- Task overview and completion status
-- List of completed subtasks
-- Files created and modified (detected from git history)
-- Code change summaries with analysis
-- Task creation and completion dates
-
-**Report location:** `.task-flow/docs/task-X-implementation.md`
+**Output:** `.task-flow/guides/reports/task-X-implementation.md`
 
 **Examples:**
-- `task-flow: report 1` → Generates report for task 1
-- `task-flow: report 10,11` → Generates reports for tasks 10 and 11
-- `task-flow: report all` → Generates reports for all tasks
-
----
-
-## Files
-
-- `.task-flow/tasks.input.txt` - Edit tasks here (format: `- Task description`)
-- `.task-flow/tasks.status.md` - ⚠️ **DO NOT EDIT** - Automatically updated by AI
-- `.task-flow/tasks.flow.md` - Dependencies, estimated hours, and model recommendations (populated by `task-flow: generate flow`)
-- `.task-flow/.internal/` - ⚠️ **IGNORE** - Internal system files (no need to read or edit)
+- `task-flow: report 1` → Report for task 1
+- `task-flow: report 10,11` → Reports for tasks 10 and 11

package/.task-flow/{AI-PLATFORMS.md → guides/AI-PLATFORMS.md}

@@ -10,7 +10,7 @@ Os comandos `task-flow: …` são **os mesmos** em Claude Code, Cursor e Codex.
 |------------|------|------------------|----------------------|
 | **Claude Code** | [platforms/claude-code.md](platforms/claude-code.md) | `CLAUDE.md` + `.claude/skills/*/SKILL.md` | **Skills no `init`** — `/task-flow-run`, etc. |
 | **Cursor** | [platforms/cursor.md](platforms/cursor.md) | `task-flow-cursor.mdc` + `rbin-git-policy.mdc` + skills | **Otimizado v1.23** — 2 always-on + `@task-flow-*` |
-| **OpenAI Codex** | [platforms/codex.md](platforms/codex.md) | `AGENTS.md` + `.task-flow/CODEX.md` + `.codex/config.toml` | **Otimizado v1.21** — sync/run no AGENTS.md |
+| **OpenAI Codex** | [platforms/codex.md](platforms/codex.md) | `AGENTS.md` + `.task-flow/guides/CODEX.md` + `.codex/config.toml` | **Otimizado v1.21** — sync/run no AGENTS.md |
 
 ---
 
@@ -37,7 +37,7 @@ Os comandos `task-flow: …` são **os mesmos** em Claude Code, Cursor e Codex.
 5. `task-flow: check`
 6. **Você** faz `git commit` (a IA só sugere)
 
-Detalhes dos comandos: [README.md](README.md).
+Detalhes dos comandos: [README.md](../README.md).
 
 ---
 
@@ -49,9 +49,9 @@ Detalhes dos comandos: [README.md](README.md).
 | `.cursor/rules/` | leitura manual | ✅ auto | leitura manual |
 | `CLAUDE.md` | ✅ | — | — |
 | `AGENTS.md` | — | — | ✅ |
-| `.task-flow/CODEX.md` | — | — | ✅ |
-| `.task-flow/CURSOR.md` | — | ✅ | — |
-| `.task-flow/docs/coding-standards-full.md` | on demand | on demand (sections only) | on demand |
+| `.task-flow/guides/CODEX.md` | — | — | ✅ |
+| `.task-flow/guides/CURSOR.md` | — | ✅ | — |
+| `.task-flow/guides/coding-standards-full.md` | on demand | on demand (sections only) | on demand |
 | [OPTIMIZATION-PLAN.md](OPTIMIZATION-PLAN.md) | — | token roadmap | — |
 | `.codex/config.toml` | — | — | ✅ (opcional, preservado no update) |
 | `task-flow-cursor.mdc` | — | ✅ always-on | — |

package/.task-flow/{CODEX.md → guides/CODEX.md}

@@ -120,7 +120,7 @@ Rule: `.cursor/rules/task_estimate.mdc`
 
 ## task-flow: report X
 
-Verify task done; write `.task-flow/docs/task-X-implementation.md`.
+Verify task done; write `.task-flow/guides/reports/task-X-implementation.md`.
 
 Rule: `.cursor/rules/task_report.mdc`
 
@@ -136,13 +136,13 @@ Rule: `.cursor/rules/task_generate_flow.mdc`
 
 ## Implementing code (any subtask)
 
-Follow the checklist in `.cursor/rules/coding_standards.mdc`. For examples/Nest: read sections of `.task-flow/docs/coding-standards-full.md` only.
+Follow the checklist in `.cursor/rules/coding_standards.mdc`. For examples/Nest: read sections of `.task-flow/guides/coding-standards-full.md` only.
 
 ---
 
 ## Graphify (optional)
 
-Only during `run` / `think` when `graphify-out/` exists. See `.task-flow/GRAPHIFY.md`. Does not replace status updates.
+Only during `run` / `think` when `graphify-out/` exists. See `.task-flow/guides/GRAPHIFY.md`. Does not replace status updates.
 
 ---
 

package/.task-flow/{CURSOR.md → guides/CURSOR.md}

@@ -43,7 +43,7 @@ Verify: `rg 'alwaysApply: true' .cursor/rules` → only the two files above.
 | **Glob** | `task-flow-sync`, `task_generation` (`.task-flow/**`), `coding_standards` (`src/**`, `app/**`), `code_comments` | Matching paths in chat |
 | **Manual** | `@cursor_rules`, `@self_improve`, `@task_report`, legacy `git_control` | You `@`-mention only (no `description` auto-match) |
 
-**Coding standards:** checklist in `coding_standards.mdc` (glob). Full reference: `.task-flow/docs/coding-standards-full.md` — **sections only**, never whole file.
+**Coding standards:** checklist in `coding_standards.mdc` (glob). Full reference: `.task-flow/guides/coding-standards-full.md` — **sections only**, never whole file.
 
 If a command fails to trigger, use **`@task-flow-*`** explicitly.
 
@@ -90,6 +90,6 @@ Only during `run` / `think` when `graphify-out/` exists. Does not replace Task F
 ## References
 
 - [platforms/cursor.md](platforms/cursor.md) — full guide
-- [README.md](README.md) — all commands
+- [README.md](../README.md) — all commands
 - [AI-PLATFORMS.md](AI-PLATFORMS.md) — install matrix
 - [Cursor Rules docs](https://cursor.com/docs/context/rules)

package/.task-flow/{GRAPHIFY.md → guides/GRAPHIFY.md}

@@ -69,7 +69,7 @@ task-flow: run next 2 — se graphify-out existir, graphify query "<módulo da s
 ## Claude Code
 
 - Use **`/graphify`** ou `graphify query` **durante** `task-flow: run`, não no lugar de atualizar status.
-- Se já rodou `graphify claude install` no passado: o hook PreToolUse pode ajudar; evite duplicar parágrafos longos no `CLAUDE.md` — priorize [.task-flow/platforms/claude-code.md](platforms/claude-code.md).
+- Se já rodou `graphify claude install` no passado: o hook PreToolUse pode ajudar; evite duplicar parágrafos longos no `CLAUDE.md` — priorize [platforms/claude-code.md](platforms/claude-code.md).
 
 ## Cursor
 
@@ -79,7 +79,7 @@ task-flow: run next 2 — se graphify-out existir, graphify query "<módulo da s
 ## Codex
 
 - Graphify não entra no `AGENTS.md` automaticamente (limite 32 KiB).
-- No prompt: cite `.task-flow/GRAPHIFY.md` + `graphify query` ao executar `run`.
+- No prompt: cite `.task-flow/guides/GRAPHIFY.md` + `graphify query` ao executar `run`.
 
 ---
 
@@ -109,5 +109,5 @@ task-flow: run next 2 — se graphify-out existir, graphify query "<módulo da s
 ## Referências
 
 - [AI-PLATFORMS.md](AI-PLATFORMS.md) — índice Claude / Cursor / Codex
-- [README.md](README.md) — comandos Task Flow
+- [README.md](../README.md) — comandos Task Flow
 - Graphify CLI: `graphify --help`

package/.task-flow/{OPTIMIZATION-IMPLEMENTATION-TASKS.md → guides/OPTIMIZATION-IMPLEMENTATION-TASKS.md}

@@ -92,7 +92,7 @@ Task 10–13 (P2) ───────────► após P0 completo
 
 **Instruções:**
 1. Criar `.task-flow/docs/` se não existir.
-2. Copiar corpo atual de `.cursor/rules/coding_standards.mdc` (sem frontmatter) para `.task-flow/docs/coding-standards-full.md`.
+2. Copiar corpo atual de `.cursor/rules/coding_standards.mdc` (sem frontmatter) para `.task-flow/guides/coding-standards-full.md`.
 3. Adicionar cabeçalho no full doc: “Carregar sob demanda — audit profundo, dúvidas de arquitetura; não colar no chat inteiro.”
 
 **Critério de aceite:** `coding-standards-full.md` ≥ linhas do antigo corpo; nenhuma seção crítica perdida.
@@ -105,7 +105,7 @@ Task 10–13 (P2) ───────────► após P0 completo
 
 **Instruções:**
 1. Manter frontmatter: `alwaysApply: false`, `globs: src/**,app/**`, `description` clara.
-2. Corpo **80–120 linhas**: estrutura `app/features/shared`; app thin; page orchestrator; service+use-case; RHF+zod; `cn()`; sem `any`; sem raw button/input; naming suffixes (tabela compacta); link `mdc:.task-flow/docs/coding-standards-full.md` para detalhes.
+2. Corpo **80–120 linhas**: estrutura `app/features/shared`; app thin; page orchestrator; service+use-case; RHF+zod; `cn()`; sem `any`; sem raw button/input; naming suffixes (tabela compacta); link `mdc:.task-flow/guides/coding-standards-full.md` para detalhes.
 3. Remover exemplos de código longos do `.mdc` (ficam no full doc).
 
 **Critério de aceite:** `wc -l .cursor/rules/coding_standards.mdc` ≤ 130; `wc -c` ≤ 6 KB.
@@ -163,7 +163,7 @@ Task 10–13 (P2) ───────────► após P0 completo
 
 **Instruções:**
 1. `.claude/skills/rbin-coding-standards/SKILL.md`: `disable-model-invocation: true`.
-2. Steps: (1) aplicar checklist em `coding_standards.mdc`; (2) só se ambíguo, ler `.task-flow/docs/coding-standards-full.md` seções relevantes — **não** colar arquivo inteiro no chat.
+2. Steps: (1) aplicar checklist em `coding_standards.mdc`; (2) só se ambíguo, ler `.task-flow/guides/coding-standards-full.md` seções relevantes — **não** colar arquivo inteiro no chat.
 3. `reference.md`: paths atualizados para checklist + full doc.
 
 **Critério de aceite:** skill não referencia “ler coding_standards.mdc inteiro” como passo 1.
@@ -215,7 +215,7 @@ Task 10–13 (P2) ───────────► após P0 completo
 **Instruções:**
 1. `task-flow-audit`, `task-flow-improve-changes`, `task-flow-sync` SKILL.md: paths checklist + full.
 2. `AGENTS.md` tabela Commands: audit/implement → checklist; full path explícito opcional.
-3. `.task-flow/CODEX.md`: mesma distinção.
+3. `.task-flow/guides/CODEX.md`: mesma distinção.
 
 **Critério de aceite:** AGENTS.md não manda “ler coding_standards.mdc inteiro” sem qualificador.
 
@@ -362,4 +362,4 @@ Após sync, o gerador de subtasks pode expandir cada linha usando as **Instruç
 
 ---
 
-*Referência: [OPTIMIZATION-PLAN.md](OPTIMIZATION-PLAN.md) · Índice: [README.md](README.md)*
+*Referência: [OPTIMIZATION-PLAN.md](OPTIMIZATION-PLAN.md) · Índice: [README.md](../README.md)*

package/.task-flow/{OPTIMIZATION-PLAN.md → guides/OPTIMIZATION-PLAN.md}

@@ -70,7 +70,7 @@ Estimativa ~4 caracteres/token.
 
 ### 4.2 `coding_standards.mdc` — ✅ resolvido (P0.2)
 
-- **Checklist** (~100 linhas, glob `src/**`) + **full** em `.task-flow/docs/coding-standards-full.md` sob demanda.
+- **Checklist** (~100 linhas, glob `src/**`) + **full** em `.task-flow/guides/coding-standards-full.md` sob demanda.
 - Skill `rbin-coding-standards`: `disable-model-invocation: true`; lê seções do full doc só se ambíguo.
 
 ### 4.3 Duplicação skill + regra no `run` — parcial (P0.3 ✅)
@@ -128,7 +128,7 @@ Estimativa ~4 caracteres/token.
 | # | Ação | Arquivos / notas | Status |
 |---|------|------------------|--------|
 | P0.1 | Fundir `git_control` + `commit_practices` em uma regra always (~70–90 linhas) | `.cursor/rules/rbin-git-policy.mdc` ou nome equivalente; remover always duplicado | [x] |
-| P0.2 | Dividir standards: **checklist** (glob) + **full** (sob demanda) | `coding_standards.mdc` enxuto; `.task-flow/docs/coding-standards-full.md` com conteúdo atual | [x] |
+| P0.2 | Dividir standards: **checklist** (glob) + **full** (sob demanda) | `coding_standards.mdc` enxuto; `.task-flow/guides/coding-standards-full.md` com conteúdo atual | [x] |
 | P0.3 | Enxugar `task_work.mdc` → pointer para `@task-flow-run` / `workflow.md` | ~40 linhas máx. | [x] |
 | P0.4 | Enxugar `task_execution.mdc` → pointer para `task-flow-cursor` + skills | Evitar índice duplicado de `CLAUDE.md` | [x] |
 | P0.5 | `rbin-coding-standards`: `disable-model-invocation: true` | `.claude/skills/` + cópia `.cursor/skills/` | [x] |
@@ -163,7 +163,7 @@ Estimativa ~4 caracteres/token.
 
 ```text
 .cursor/rules/coding_standards.mdc     # ~80–120 linhas: checklist + links
-.task-flow/docs/coding-standards-full.md   # conteúdo atual (exemplos, Nest, RHF…)
+.task-flow/guides/coding-standards-full.md   # conteúdo atual (exemplos, Nest, RHF…)
 .claude/skills/rbin-coding-standards/
   SKILL.md          # aponta checklist + “read full doc if ambiguous”
   reference.md      # já existe; alinhar paths

package/.task-flow/{docs → guides}/coding-standards-full.md

@@ -8,6 +8,151 @@ These rules define how code MUST be written when implementing tasks. Always foll
 
 ---
 
+## Vercel — environment variables
+
+**When the project deploys on Vercel** (Next.js, etc.), follow this section for `.env` files.
+
+### Instruções para a IA (executar nesta ordem)
+
+1. **Antes de tudo — auditar variáveis sem uso** [§0]: para cada variável dos `.env*`, verifique se ela é realmente referenciada no código/configuração. **Liste as órfãs e confirme com o usuário antes de remover** — não apague sozinha (algumas são usadas só em runtime/CI/infra). Só depois de limpar é que se alinham os 3 arquivos.
+2. Crie `scripts/env-files-check.sh` e `scripts/vercel-env-sync.sh` com **exatamente** o conteúdo das seções [§5] e [§6]. Marque ambos como executáveis (`chmod +x`).
+3. Garanta os **3 arquivos de ambiente** seguindo a convenção [§1]: mesma sequência de chaves nos 3, **ordem alfabética**, uma variável por linha, sem comentários de seção no meio. Crie `.env.example` (commitado, valores vazios). **Nunca** coloque valores reais no `.env.example`.
+4. Ajuste o `.gitignore` conforme [§2].
+5. Ajuste a `PLAINTEXT_REGEX` do `vercel-env-sync.sh` ao stack do projeto [§3].
+6. Rode `./scripts/env-files-check.sh` e mostre a saída. Não rode o sync da Vercel sem credenciais do usuário — explique os comandos de [§4].
+7. Confirme os **critérios de aceite** [§7].
+
+### §0 — Auditoria (variáveis sem uso)
+
+Para cada chave dos `.env*`, procure referências: `process.env.NOME`, `import.meta.env.NOME`, `env("NOME")`, configs/CI (`vercel.json`, `*.yml`, `Dockerfile`).
+
+```bash
+for k in $(grep -hE '^[A-Za-z_][A-Za-z0-9_]*=' .env.example .env.local .env.production 2>/dev/null \
+            | sed -E 's/=.*//' | sort -u); do
+  n=$(grep -rIn --exclude-dir=node_modules --exclude-dir=.git --exclude='.env*' \
+        -e "$k" . 2>/dev/null | wc -l | tr -d ' ')
+  printf '%-32s %s ref(s)\n' "$k" "$n"
+done
+```
+
+**Trate `0 ref` como candidata, não certeza.** Confirme com o usuário antes de remover.
+
+### §1 — Convenção dos 3 arquivos
+
+| Arquivo | Commitado? | Papel | Valores |
+|---|---|---|---|
+| `.env.example` | ✅ sim | Lista canônica (doc) | vazios/placeholder |
+| `.env.local` | ❌ não | Desenvolvimento local | reais de dev |
+| `.env.production` | ❌ não | **Sincronizado com a Vercel** | reais de produção |
+
+Mesma sequência de chaves, **ordem alfabética**. Sem comentários de seção no meio.
+
+### §2 — `.gitignore`
+
+```gitignore
+.env
+.env.*
+!.env.example
+```
+
+### §3 — Classificação secret × plaintext (Vercel)
+
+| Classe | Exemplos | Tipo |
+|---|---|---|
+| `NEXT_PUBLIC_*` | `NEXT_PUBLIC_API_URL` | **plaintext** |
+| Flags / URLs públicas | `*_ENABLED`, `*_PUBLIC_URL`, `NODE_ENV` | **plaintext** |
+| Todo o resto | `*_API_KEY`, `*_SECRET`, `*_TOKEN` | **secret** (`--sensitive`) |
+
+### §4 — Comandos
+
+```bash
+npm i -g vercel && vercel login && vercel link
+./scripts/env-files-check.sh
+DRY_RUN=1 ./scripts/vercel-env-sync.sh
+./scripts/vercel-env-sync.sh
+vercel env pull .env.vercel.check --environment=production
+```
+
+### §5 — `scripts/env-files-check.sh`
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+if [ "$#" -gt 0 ]; then FILES=("$@"); else FILES=(".env.example" ".env.local" ".env.production"); fi
+keys_of() { grep -E '^[A-Za-z_][A-Za-z0-9_]*=' "$1" | sed -E 's/=.*//'; }
+fail=0; ref=""; ref_file=""
+for f in "${FILES[@]}"; do
+  if [ ! -f "$f" ]; then echo "❌ faltando: $f"; fail=1; continue; fi
+  keys="$(keys_of "$f")"
+  sorted="$(printf '%s\n' "$keys" | LC_ALL=C sort)"
+  if [ "$keys" != "$sorted" ]; then
+    echo "❌ $f não está em ordem alfabética."
+    diff <(printf '%s\n' "$keys") <(printf '%s\n' "$sorted") | head -6
+    fail=1
+  fi
+  count="$(printf '%s\n' "$keys" | grep -c . || true)"
+  echo "• $f — $count variáveis"
+  if [ -z "$ref" ]; then ref="$sorted"; ref_file="$f"
+  elif [ "$sorted" != "$ref" ]; then
+    echo "❌ $f difere de $ref_file:"
+    diff <(printf '%s\n' "$ref") <(printf '%s\n' "$sorted") || true
+    fail=1
+  fi
+done
+if [ "$fail" -eq 0 ]; then echo "✅ Arquivos alinhados, mesma sequência e em ordem alfabética."
+else echo "→ Corrija as divergências acima."; fi
+exit "$fail"
+```
+
+### §6 — `scripts/vercel-env-sync.sh`
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+ENV_FILE="${1:-.env.production}"
+TARGET="${2:-production}"
+DRY_RUN="${DRY_RUN:-0}"
+PLAINTEXT_REGEX="${PLAINTEXT_REGEX:-^(NEXT_PUBLIC_|NODE_ENV$|.*_ENABLED$|.*_URL_STRATEGY$|.*_PUBLIC_URL$|.*_REGION$)}"
+command -v vercel >/dev/null 2>&1 || { echo "❌ vercel CLI não encontrado. Instale: npm i -g vercel"; exit 1; }
+[ -f "$ENV_FILE" ] || { echo "❌ arquivo não encontrado: $ENV_FILE"; exit 1; }
+[ -d ".vercel" ] || echo "⚠️  projeto não vinculado — rode 'vercel link' antes (continuando…)"
+secret_count=0; plain_count=0
+while IFS= read -r line <&3 || [ -n "$line" ]; do
+  case "$line" in ''|\#*) continue ;; esac
+  case "$line" in *=*) ;; *) continue ;; esac
+  key="${line%%=*}"; val="${line#*=}"
+  key="$(printf '%s' "$key" | tr -d '[:space:]')"
+  val="${val%\"}"; val="${val#\"}"; val="${val%\'}"; val="${val#\'}"
+  [ -z "$key" ] && continue
+  if [ -z "$val" ]; then echo "⏭️  $key (valor vazio — pulado)"; continue; fi
+  if printf '%s' "$key" | grep -Eq "$PLAINTEXT_REGEX"; then
+    flag=""; kind="plaintext"; plain_count=$((plain_count+1))
+  else
+    flag="--sensitive"; kind="secret  "; secret_count=$((secret_count+1))
+  fi
+  echo "→ [$kind] $key  ($TARGET)"
+  [ "$DRY_RUN" = "1" ] && continue
+  vercel env rm "$key" "$TARGET" -y </dev/null >/dev/null 2>&1 || true
+  printf '%s' "$val" | vercel env add "$key" "$TARGET" $flag >/dev/null
+done 3< "$ENV_FILE"
+echo "✅ $secret_count secret(s), $plain_count plaintext em '$TARGET'."
+[ "$DRY_RUN" = "1" ] && echo "(DRY_RUN — nada foi enviado)"
+```
+
+### §7 — Critérios de aceite
+
+- Auditoria [§0] feita; órfãs removidas após confirmação do usuário.
+- Scripts executáveis; 3 arquivos com mesma sequência alfabética.
+- `./scripts/env-files-check.sh` retorna exit 0.
+- `.gitignore` ignora `.env*` exceto `.env.example`.
+- Nenhum valor real no `.env.example` nem no git.
+
+### §8 — Limitações
+
+Valores multilinha (PEM/JSON) → base64 numa linha ou cadastro manual na Vercel. `NEXT_PUBLIC_*` no target do **build**.
+
+---
+
 ## Project Structure
 
 All projects use TypeScript and follow this structure:

package/.task-flow/{platforms → guides/platforms}/claude-code.md

@@ -344,7 +344,7 @@ Durante **`task-flow: run`**, use `/graphify` ou `graphify query` para achar mó
 
 - [Claude Code — Skills](https://code.claude.com/docs/en/skills)
 - [Agent Skills open standard](https://agentskills.io/) (interoperável com Cursor)
-- Comandos Task Flow: [../README.md](../README.md)
+- Comandos Task Flow: [../../README.md](../../README.md)
 - Regras completas: `../../.cursor/rules/`
 
 ---

package/.task-flow/{platforms → guides/platforms}/codex.md

@@ -65,7 +65,7 @@ projeto/
 └── .cursor/rules/            # Lidos quando AGENTS.md / CODEX.md indicam
 ```
 
-**v1.21+:** `sync` e `run` vêm **resumidos no AGENTS.md** (~dentro do orçamento 32–64 KiB). Demais comandos → ler `.task-flow/CODEX.md` ou `.mdc` indicado.
+**v1.21+:** `sync` e `run` vêm **resumidos no AGENTS.md** (~dentro do orçamento 32–64 KiB). Demais comandos → ler `.task-flow/guides/CODEX.md` ou `.mdc` indicado.
 
 Verifique após init:
 
@@ -324,10 +324,10 @@ Codex **não** substitui `task-flow: sync` — isso é trabalho do agente lendo
 ## 13. Checklist de maturidade Codex + Task Flow
 
 - [x] `AGENTS.md` otimizado após `init` (sync/run embutidos + tabela)
-- [x] `.task-flow/CODEX.md` para workflows sob demanda
+- [x] `.task-flow/guides/CODEX.md` para workflows sob demanda
 - [x] `.codex/config.toml` com `project_doc_max_bytes = 65536`
 - [ ] Tamanho `AGENTS.md` < ~28 KiB se não usar config.toml
-- [ ] Prompts citam `AGENTS.md` + `.task-flow/CODEX.md` para `run`
+- [ ] Prompts citam `AGENTS.md` + `.task-flow/guides/CODEX.md` para `run`
 - [ ] `improve changes` + `check` antes de PR
 - [ ] `AGENTS.md` em subpastas de monorepo se necessário
 
@@ -351,10 +351,10 @@ pnpm lint:fix && pnpm build && pnpm test
 Nunca executar git write. Sugerir Conventional Commits + Task/Subtask ID.
 
 ## Coding standards
-Ao implementar código, seguir o checklist em `.cursor/rules/coding_standards.mdc`; exemplos completos em `.task-flow/docs/coding-standards-full.md` (só seções necessárias).
+Ao implementar código, seguir o checklist em `.cursor/rules/coding_standards.mdc`; exemplos completos em `.task-flow/guides/coding-standards-full.md` (só seções necessárias).
 
 ## Mais detalhe
-- Task Flow por plataforma: `.task-flow/platforms/codex.md`
+- Task Flow por plataforma: `.task-flow/guides/platforms/codex.md`
 - Comandos: `.task-flow/README.md`
 ```
 

package/.task-flow/{platforms → guides/platforms}/cursor.md

@@ -89,7 +89,7 @@ Confirme no projeto: `rg 'alwaysApply: true' .cursor/rules` → deve listar **ap
 | `cursor_rules.mdc` | formato `.mdc` | **Glob** `.cursor/rules/**` |
 | `self_improve.mdc` | evoluir regras | Manual `@self_improve` |
 
-**Doc (não é regra):** `.task-flow/docs/coding-standards-full.md` — seções sob demanda; nunca colar inteiro no chat.
+**Doc (não é regra):** `.task-flow/guides/coding-standards-full.md` — seções sob demanda; nunca colar inteiro no chat.
 
 ### Otimização P0 — implementada
 
@@ -325,7 +325,7 @@ Com Graphify instalado (`rbin-install-dev`), o Task Flow traz **`graphify-task-f
 
 - [Cursor — Rules](https://cursor.com/docs/context/rules)
 - [Agent Skills standard](https://agentskills.io/)
-- Comandos: [../README.md](../README.md)
+- Comandos: [../../README.md](../../README.md)
 - Claude (skills espelhadas): [claude-code.md](claude-code.md)
 
 ---

package/AGENTS.md

@@ -2,7 +2,7 @@
 
 **Task flow** always means **RBIN Task Flow**. Codex does not load `.cursor/rules/*.mdc` automatically — use this file plus **read on demand** files below.
 
-**Full Codex guide:** `.task-flow/platforms/codex.md` · **Workflows (read when executing a command):** `.task-flow/CODEX.md`
+**Full Codex guide:** `.task-flow/guides/platforms/codex.md` · **Workflows (read when executing a command):** `.task-flow/guides/CODEX.md`
 
 ## Paths
 
@@ -28,20 +28,20 @@ No explanatory comments. Complex topics → `dev-logs/*.md`. Allowed: `// ──
 
 | Command | Read first |
 |---------|------------|
-| `task-flow: sync` | Section **Sync** below; details `.task-flow/CODEX.md` |
-| `task-flow: run …` | Section **Run** below; details `.task-flow/CODEX.md` |
+| `task-flow: sync` | Section **Sync** below; details `.task-flow/guides/CODEX.md` |
+| `task-flow: run …` | Section **Run** below; details `.task-flow/guides/CODEX.md` |
 | `task-flow: status` | `.task-flow/tasks.status.md` |
-| `task-flow: think` | `.task-flow/CODEX.md` · optional codebase scan |
+| `task-flow: think` | `.task-flow/guides/CODEX.md` · optional codebase scan |
 | `task-flow: check` | `.cursor/rules/task_check.mdc` · `package.json` |
 | `task-flow: improve changes` | `git diff --name-only HEAD` · `.cursor/rules/task_improve_changes.mdc` |
-| `task-flow: audit` | `.cursor/rules/task_audit.mdc` · checklist `coding_standards.mdc` (full: `.task-flow/docs/coding-standards-full.md` if needed) |
-| `task-flow: review X` | `.task-flow/CODEX.md` |
+| `task-flow: audit` | `.cursor/rules/task_audit.mdc` · checklist `coding_standards.mdc` (full: `.task-flow/guides/coding-standards-full.md` if needed) |
+| `task-flow: review X` | `.task-flow/guides/CODEX.md` |
 | `task-flow: validate` | `.cursor/rules/task_validate.mdc` · then sync |
 | `task-flow: refactor X` | `.cursor/rules/task_refactor.mdc` |
-| `task-flow: estimate X` | `.task-flow/CODEX.md` |
-| `task-flow: report X` | `.task-flow/CODEX.md` |
+| `task-flow: estimate X` | `.task-flow/guides/CODEX.md` |
+| `task-flow: report X` | `.task-flow/guides/CODEX.md` |
 | `task-flow: generate flow` | `.cursor/rules/task_generate_flow.mdc` |
-| Implementing code | Checklist `.cursor/rules/coding_standards.mdc` · depth: `.task-flow/docs/coding-standards-full.md` (sections only) |
+| Implementing code | Checklist `.cursor/rules/coding_standards.mdc` · depth: `.task-flow/guides/coding-standards-full.md` (sections only) |
 
 ## Sync (embedded)
 
@@ -71,7 +71,7 @@ Leia AGENTS.md. Execute task-flow: sync.
 ```
 
 ```
-Leia AGENTS.md e .task-flow/CODEX.md (Run). task-flow: run next 3.
+Leia AGENTS.md e .task-flow/guides/CODEX.md (Run). task-flow: run next 3.
 ```
 
 ```
@@ -80,4 +80,4 @@ task-flow: improve changes — git diff --name-only HEAD, audite só esses arqui
 
 ## Other platforms
 
-Claude: `CLAUDE.md` + `.claude/skills/`. Cursor: `.cursor/rules/`. Index: `.task-flow/AI-PLATFORMS.md`.
+Claude: `CLAUDE.md` + `.claude/skills/`. Cursor: `.cursor/rules/`. Index: `.task-flow/guides/AI-PLATFORMS.md`.

package/CLAUDE.md

@@ -34,8 +34,8 @@ Natural language `task-flow: …` works the same. Details: [.task-flow/README.md
 ## Anti-patterns (save context)
 
 - Prefer **`/task-flow-run`** (or `@task-flow-run`) for executing subtasks — avoid `@task_work` plus duplicate `.cursor/rules/task_work.mdc` in the same turn.
-- Do **not** load `.task-flow/docs/coding-standards-full.md` unless the user asks for depth; use `/rbin-coding-standards` checklist or `coding_standards.mdc` for normal implementation.
-- Cursor users: see [.task-flow/CURSOR.md](.task-flow/CURSOR.md) for always-on vs skills (`@task-flow-*`).
+- Do **not** load `.task-flow/guides/coding-standards-full.md` unless the user asks for depth; use `/rbin-coding-standards` checklist or `coding_standards.mdc` for normal implementation.
+- Cursor users: see [.task-flow/guides/CURSOR.md](.task-flow/guides/CURSOR.md) for always-on vs skills (`@task-flow-*`).
 
 ## Git
 
@@ -43,7 +43,7 @@ Natural language `task-flow: …` works the same. Details: [.task-flow/README.md
 
 ## Graphify (optional)
 
-During `/task-flow-run`, if `graphify-out/` exists, use `graphify query` before broad search. See [.task-flow/GRAPHIFY.md](.task-flow/GRAPHIFY.md).
+During `/task-flow-run`, if `graphify-out/` exists, use `graphify query` before broad search. See [.task-flow/guides/GRAPHIFY.md](.task-flow/guides/GRAPHIFY.md).
 
 ## Cursor rules (reference)
 
@@ -51,9 +51,9 @@ Full procedures also live in `.cursor/rules/` (shared with Cursor). Claude Code
 
 ## Other platforms
 
-- Index: [.task-flow/AI-PLATFORMS.md](.task-flow/AI-PLATFORMS.md)
-- Claude: [.task-flow/platforms/claude-code.md](.task-flow/platforms/claude-code.md)
-- Codex: [AGENTS.md](AGENTS.md) · [.task-flow/CODEX.md](.task-flow/CODEX.md)
+- Index: [.task-flow/guides/AI-PLATFORMS.md](.task-flow/guides/AI-PLATFORMS.md)
+- Claude: [.task-flow/guides/platforms/claude-code.md](.task-flow/guides/platforms/claude-code.md)
+- Codex: [AGENTS.md](AGENTS.md) · [.task-flow/guides/CODEX.md](.task-flow/guides/CODEX.md)
 
 ## Models
 

package/README.md

@@ -33,7 +33,7 @@
 <a id="português"></a>
 # 🇧🇷 Português
 
-> **v1.24.0** — Novo `task-flow: validate` (auditoria profunda + lacunas automáticas). De **1.23.x**: `npm install -g rbin-task-flow@1.24` e `rbin-task-flow update`. [CHANGELOG](CHANGELOG.md) · [Publicação](RELEASE-1.24.0.md).
+> **v1.25.1** — Padrão `.env` Vercel nos coding standards. De **1.25.0**: `npm install -g rbin-task-flow@1.25.1` e `rbin-task-flow update`. [CHANGELOG](CHANGELOG.md) · [Publicação](RELEASE-1.25.1.md).
 
 ## O Que É Este Projeto?
 
@@ -89,15 +89,15 @@ rbin-task-flow report <ids>  # Gera relatório (ex: "1" ou "1,2" ou "all")
 
 Após inicializar, use estes comandos na IA (Cursor/Claude/Codex) para gerenciar tarefas automaticamente.
 
-**Otimizar por plataforma:** [.task-flow/AI-PLATFORMS.md](.task-flow/AI-PLATFORMS.md) · [Claude](.task-flow/platforms/claude-code.md) · [Cursor](.task-flow/platforms/cursor.md) · [Codex](.task-flow/platforms/codex.md) · [Graphify](.task-flow/GRAPHIFY.md)
+**Otimizar por plataforma:** [.task-flow/guides/AI-PLATFORMS.md](.task-flow/guides/AI-PLATFORMS.md) · [Claude](.task-flow/guides/platforms/claude-code.md) · [Cursor](.task-flow/guides/platforms/cursor.md) · [Codex](.task-flow/guides/platforms/codex.md) · [Graphify](.task-flow/guides/GRAPHIFY.md)
 
 **Graphify (opcional):** `rbin-task-flow init --graphify` configura coexistência e roda `graphify extract . --backend claude-cli` (CLI via `rbin-install-dev`; usa assinatura Claude Code).
 
 **Claude Code / Cursor skills (v1.20+):** `init` copia 15 skills para `.claude/skills/` e `.cursor/skills/` — use `/task-flow-sync`, `/task-flow-run`, `/task-flow-validate`, etc.
 
-**Codex (v1.21+):** `AGENTS.md` com sync/run embutidos, `.task-flow/CODEX.md` sob demanda, `.codex/config.toml` (64 KiB).
+**Codex (v1.21+):** `AGENTS.md` com sync/run embutidos, `.task-flow/guides/CODEX.md` sob demanda, `.codex/config.toml` (64 KiB).
 
-**Cursor (v1.23+):** `task-flow-cursor.mdc` + `rbin-git-policy.mdc` (2 always-on) + skills — ver `.task-flow/CURSOR.md`.
+**Cursor (v1.23+):** `task-flow-cursor.mdc` + `rbin-git-policy.mdc` (2 always-on) + skills — ver `.task-flow/guides/CURSOR.md`.
 
 **Perfil minimal:** `init --profile minimal` instala só as 2 regras always-on e as 15 skills; workflows via `@task-flow-*` (sem `task_work`, `coding_standards` glob, etc.). `standard` (padrão) copia todas as regras `.cursor/rules/`.
 
@@ -419,7 +419,7 @@ Para problemas ou perguntas:
 <a id="english"></a>
 # 🇬🇧 English
 
-> **v1.24.0** — New `task-flow: validate` (deep audit + auto gap fill). From **1.23.x**: `npm install -g rbin-task-flow@1.24` then `rbin-task-flow update`. [CHANGELOG](CHANGELOG.md) · [Release guide](RELEASE-1.24.0.md).
+> **v1.25.1** — Vercel `.env` pattern in coding standards. From **1.25.0**: `npm install -g rbin-task-flow@1.25.1` then `rbin-task-flow update`. [CHANGELOG](CHANGELOG.md) · [Release guide](RELEASE-1.25.1.md).
 
 ## What Is This Project?
 
@@ -475,13 +475,13 @@ rbin-task-flow report <ids>   # Generate report (e.g., "1" or "1,2" or "all")
 
 After initializing, use these commands in your AI (Cursor/Claude/Codex) to automatically manage tasks.
 
-**Per-platform optimization:** [index](.task-flow/AI-PLATFORMS.md) · [Claude](.task-flow/platforms/claude-code.md) · [Cursor](.task-flow/platforms/cursor.md) · [Codex](.task-flow/platforms/codex.md) · [Graphify](.task-flow/GRAPHIFY.md)
+**Per-platform optimization:** [index](.task-flow/guides/AI-PLATFORMS.md) · [Claude](.task-flow/guides/platforms/claude-code.md) · [Cursor](.task-flow/guides/platforms/cursor.md) · [Codex](.task-flow/guides/platforms/codex.md) · [Graphify](.task-flow/guides/GRAPHIFY.md)
 
 **Graphify (optional):** `rbin-task-flow init --graphify` — cooperative setup + runs `graphify extract . --backend claude-cli` (CLI from `rbin-install-dev`; uses Claude Code subscription).
 
 **Claude / Cursor skills (v1.20+):** installs 15 skills — use `/task-flow-sync`, `/task-flow-run`, `/task-flow-validate`, etc.
 
-**Codex (v1.21+):** optimized `AGENTS.md`, `.task-flow/CODEX.md`, `.codex/config.toml`.
+**Codex (v1.21+):** optimized `AGENTS.md`, `.task-flow/guides/CODEX.md`, `.codex/config.toml`.
 
 **Cursor (v1.23+):** 2 always-on rules + 15 skills — `@task-flow-sync`, `@task-flow-run`, `@task-flow-validate`.
 

package/lib/codex.js

@@ -23,7 +23,7 @@ async function setupCodexIntegration(targetPath, options = {}) {
 
   const codexWorkflows = path.join(targetPath, '.task-flow', 'CODEX.md');
   if (fs.existsSync(codexWorkflows)) {
-    showInfo('Codex workflows: .task-flow/CODEX.md (read on demand)');
+    showInfo('Codex workflows: .task-flow/guides/CODEX.md (read on demand)');
   }
 
   showInfo('Codex entry: AGENTS.md — embedded sync/run + command table');

package/lib/cursor.js

@@ -20,7 +20,7 @@ async function setupCursorIntegration(targetPath, options = {}) {
   }
 
   if (fs.existsSync(cursorMd)) {
-    showInfo('Cursor guide: .task-flow/CURSOR.md');
+    showInfo('Cursor guide: .task-flow/guides/CURSOR.md');
   }
 
   const gitPolicy = path.join(targetPath, '.cursor', 'rules', 'rbin-git-policy.mdc');

package/lib/graphify.js

@@ -34,7 +34,7 @@ function demoteUpstreamGraphifyRule(targetPath) {
   if (!content.includes('RBIN Task Flow')) {
     const notice = [
       '',
-      '- **RBIN Task Flow:** This file was set to `alwaysApply: false` by `rbin-task-flow` to avoid competing with Task Flow rules. Use [.cursor/rules/graphify-task-flow.mdc](mdc:.cursor/rules/graphify-task-flow.mdc) and [.task-flow/GRAPHIFY.md](mdc:.task-flow/GRAPHIFY.md) instead.',
+      '- **RBIN Task Flow:** This file was set to `alwaysApply: false` by `rbin-task-flow` to avoid competing with Task Flow rules. Use [.cursor/rules/graphify-task-flow.mdc](mdc:.cursor/rules/graphify-task-flow.mdc) and [.task-flow/guides/GRAPHIFY.md](mdc:.task-flow/guides/GRAPHIFY.md) instead.',
       '',
     ].join('\n');
     content = content.trimEnd() + notice;
@@ -108,7 +108,7 @@ async function setupGraphifyIntegration(targetPath, options = {}) {
     }
   }
 
-  showInfo('Graphify + Task Flow guide: .task-flow/GRAPHIFY.md');
+  showInfo('Graphify + Task Flow guide: .task-flow/guides/GRAPHIFY.md');
 }
 
 module.exports = {

package/lib/install.js

@@ -203,6 +203,58 @@ async function copyConfigs(targetPath, options = {}) {
   await copyTaskFlow(targetPath, { update: isUpdate, reset: isReset });
 }
 
+const LEGACY_TASK_FLOW_ROOT_FILES = [
+  'GRAPHIFY.md',
+  'CODEX.md',
+  'CURSOR.md',
+  'AI-PLATFORMS.md',
+  'OPTIMIZATION-PLAN.md',
+  'OPTIMIZATION-IMPLEMENTATION-TASKS.md',
+];
+
+async function migrateLegacyTaskFlowLayout(taskFlowDest) {
+  await fs.ensureDir(path.join(taskFlowDest, 'guides', 'reports'));
+
+  for (const file of LEGACY_TASK_FLOW_ROOT_FILES) {
+    const legacyPath = path.join(taskFlowDest, file);
+    if (fs.existsSync(legacyPath)) {
+      await fs.remove(legacyPath);
+    }
+  }
+
+  const legacyDocs = path.join(taskFlowDest, 'docs');
+  if (fs.existsSync(legacyDocs)) {
+    const standardsSrc = path.join(legacyDocs, 'coding-standards-full.md');
+    const standardsDest = path.join(taskFlowDest, 'guides', 'coding-standards-full.md');
+    if (fs.existsSync(standardsSrc) && !fs.existsSync(standardsDest)) {
+      await fs.move(standardsSrc, standardsDest);
+    }
+    const reportsDest = path.join(taskFlowDest, 'guides', 'reports');
+    const entries = await fs.readdir(legacyDocs);
+    for (const entry of entries) {
+      if (entry.startsWith('task-') && entry.endsWith('.md')) {
+        await fs.move(path.join(legacyDocs, entry), path.join(reportsDest, entry), {
+          overwrite: true,
+        });
+      }
+    }
+    await fs.remove(legacyDocs);
+  }
+
+  const legacyPlatforms = path.join(taskFlowDest, 'platforms');
+  const platformsDest = path.join(taskFlowDest, 'guides', 'platforms');
+  if (fs.existsSync(legacyPlatforms)) {
+    await fs.ensureDir(platformsDest);
+    const entries = await fs.readdir(legacyPlatforms);
+    for (const entry of entries) {
+      await fs.move(path.join(legacyPlatforms, entry), path.join(platformsDest, entry), {
+        overwrite: true,
+      });
+    }
+    await fs.remove(legacyPlatforms);
+  }
+}
+
 async function copyTaskFlow(targetPath, options = {}) {
   const isUpdate = options.update || false;
   const isReset = options.reset || false;
@@ -241,6 +293,8 @@ async function copyTaskFlow(targetPath, options = {}) {
   });
 
   await fs.ensureDir(path.join(taskFlowDest, 'contexts'));
+  await fs.ensureDir(path.join(taskFlowDest, 'guides', 'reports'));
+  await migrateLegacyTaskFlowLayout(taskFlowDest);
 
   const flowPath = path.join(taskFlowDest, 'tasks.flow.md');
   if (!fs.existsSync(flowPath)) {

package/lib/report.js

@@ -7,7 +7,7 @@ const { parseTaskIds } = require('./utils');
 async function generateReport(taskIdsInput, targetPath = process.cwd()) {
   const tasksPath = path.join(targetPath, '.task-flow/.internal/tasks.json');
   const statusPath = path.join(targetPath, '.task-flow/.internal/status.json');
-  const docsDir = path.join(targetPath, '.task-flow/docs');
+  const docsDir = path.join(targetPath, '.task-flow/guides/reports');
 
   if (!fs.existsSync(tasksPath)) {
     console.log(chalk.red('❌ Tasks file not found. Run "task-flow: sync" first.'));

package/lib/utils.js

@@ -77,8 +77,8 @@ function showNextSteps(targetPath) {
   console.log(chalk.blue('  2.'), 'Sync:', chalk.cyan('task-flow: sync'), chalk.gray('· Cursor/Claude: @task-flow-sync or /task-flow-sync'));
   console.log(chalk.blue('  3.'), 'Run:', chalk.cyan('task-flow: run next X'), chalk.gray('· @task-flow-run'));
   console.log(chalk.blue('  4.'), 'Check status:', chalk.cyan('task-flow: status'));
-  console.log(chalk.blue('  5.'), 'Codex:', chalk.gray('AGENTS.md + .task-flow/CODEX.md on demand'));
-  console.log(chalk.blue('  6.'), 'Optional Graphify:', chalk.yellow('rbin-task-flow init --graphify'), chalk.gray('— .task-flow/GRAPHIFY.md'));
+  console.log(chalk.blue('  5.'), 'Codex:', chalk.gray('AGENTS.md + .task-flow/guides/CODEX.md on demand'));
+  console.log(chalk.blue('  6.'), 'Optional Graphify:', chalk.yellow('rbin-task-flow init --graphify'), chalk.gray('— .task-flow/guides/GRAPHIFY.md'));
   console.log(chalk.cyan('═'.repeat(60)));
   console.log(chalk.blue('\n  See'), chalk.yellow('.task-flow/README.md'), chalk.blue('for all available commands\n'));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rbin-task-flow",
-  "version": "1.24.0",
+  "version": "1.25.1",
   "description": "AI-powered task management for Claude and Cursor",
   "main": "index.js",
   "bin": {