wb-flow 1.0.0-r01

package/templates/commands/wbDebug/wbDebug_template.md

@@ -0,0 +1,132 @@
+# /wbDebug: Execution Template
+
+
+<!-- HELP_GATE_START -->
+## Help intercept (handle FIRST — before any other action)
+
+**If `$ARGUMENTS` contains `--help`, `-h`, or `--h`** (case-insensitive, anywhere in the args), DO NOT execute the command's normal procedure. Instead:
+
+1. Output the **HELP BLOCK** below verbatim (rendered as markdown).
+2. Stop. Do not perform any file reads, writes, or other tool calls.
+3. Do not generate any reports under `.wb/workflows/reports/`.
+
+Otherwise, ignore this section and proceed to the rest of the template.
+
+### HELP BLOCK — `/wbDebug`
+
+## Two forms
+
+```
+/wbDebug "<error message>"        # start from the symptom
+/wbDebug <file-path>              # investigate a specific file
+```
+
+Both produce a hypothesis first, fix second. If you get a fix without a hypothesis, the command was run wrong.
+
+## When to run
+
+- First response to any error you don't immediately recognize.
+- When tests fail in ways that aren't obviously test-wrong or code-wrong.
+- When behavior is "off" but no error is thrown.
+- When inheriting bug reports you haven't investigated yet.
+
+## When *not* to run
+
+- Typo or syntax error you can see at a glance. Just fix it.
+- Bug you already know the cause of. Describe the fix directly.
+- "Is this code good?" — that's `/wbAudit`, not debug.
+
+## Reading the output
+
+Every run produces:
+
+1. **Hypothesis** — the AI's best guess, specific.
+2. **Evidence to check** — steps you can run to verify.
+3. **Pause** — waiting for your feedback.
+4. **Fix proposal or refusal** — only after hypothesis is confirmed.
+
+## The pause is non-negotiable
+
+If the AI proposes a fix without waiting for you to verify, push back:
+
+```
+"You skipped the pause. First tell me why you think this is the cause.
+Then I'll check. Then we fix."
+```
+
+The pause exists because:
+- Wrong hypothesis + fix = new bug introduced, original still there.
+- Right hypothesis + fix = clean debugging.
+- Unverified hypothesis = gamble.
+
+## When the hypothesis is wrong
+
+Tell the AI directly: "hypothesis is wrong because X." The AI should explicitly acknowledge and reform. If it defends the original hypothesis, re-prompt harder: *"I just told you the hypothesis is wrong. Accept that and reform based on my new information."*
+
+## The interaction with open decisions
+
+If `context.md` has an open architectural decision, and the bug symptom maps to that decision, the AI should **refuse to fix**. Example: `extractSubObject` array handling is open; a bug that comes from this is not a bug — it's a design question.
+
+Surface the decision. Don't silently fix.
+
+## When /wbDebug is the wrong command
+
+- Code quality review → `/wbAudit`.
+- Plan verification → `/wbReview`.
+- Finding dead code → `/wbClean`.
+- Rewriting working code → `/wbRefactor`.
+
+`/wbDebug` answers one question: *"why is this broken?"*
+
+> For deeper reading: [`docs_claude/commands/wbDebug/wbDebug_practical_claude.md`](../../docs/docs_claude/commands/wbDebug/wbDebug_practical_claude.md) (or the `_eli5_`, `_expert_`, `_examples_` siblings).
+## Self-correct mode (dual-mode invocation)
+
+```
+/wbDebug <scope_folder>           # normal mode — produce a fresh output file
+/wbDebug <previous_output_file>   # self-correct mode — verify & repair the file in place
+```
+
+When the first arg is an existing output file from a prior `/wbDebug` run (detected by its first H1 — see this template's **Detection** section), the command runs in **verify-and-repair** mode: gap-fills missing fields, normalizes links, ticks done/valid checkboxes whose reports exist, never rewrites authored content. See [`../_shared/output_conventions.md`](../_shared/output_conventions.md) §3.
+
+<!-- HELP_GATE_END -->
+
+**ROLE:** The Detective
+**TARGET:** The provided stack trace, error message, or broken file.
+**Read first:** [`../_shared/output_conventions.md`](../_shared/output_conventions.md) — applies to the debug report (relative links, full-syntax commands, self-correct mode).
+
+---
+
+## ━━━ DETECTION (Self-Correct Mode) ━━━
+
+Trigger self-correct when the input file's first H1 matches:
+`# Debug: <scope> — <YYYY-MM-DD>` *(or the legacy `# Debug Entry #N` header).*
+
+Behavior is defined in [`../_shared/output_conventions.md`](../_shared/output_conventions.md) §3.
+
+Debug-specific gap-fills:
+
+- Plain-text file paths in the Root Cause / Solution sections → relative markdown links per §1.
+- Bare `/wbTest` cited as regression check → full-syntax `/wbTest <target>` per §2.
+
+---
+
+## ━━━ OBJECTIVE ━━━
+Your job is to fix errors. Do not guess. You must follow the Scientific Method to isolate the root cause before applying a patch.
+
+## ━━━ PHASE 1: INGEST & HYPOTHESIS ━━━
+1. Analyze the provided error message or broken behavior.
+2. State your Hypothesis clearly: *Why is this failing?* (e.g., "The reactivity loop is triggering because `watch` is mutating its own dependency.")
+
+## ━━━ PHASE 2: ISOLATION ━━━
+1. If the root cause is unclear, inject `console.log` tracers or debug points to capture the state.
+2. Trace the data flow back to the origin of the mutation.
+
+## ━━━ PHASE 3: RESOLUTION & REPORT ━━━
+1. Apply the minimal necessary fix to resolve the error.
+2. Generate a report: `.wb/workflows/reports/<YYYY>/<MM>/<DD>/debugs/debug_<target>_<YYYYMMDD>.md` (create-or-append; tag your entry `*(ModelName — HH:MM)*`).
+3. The report must explain the Root Cause and the Solution applied. Apply output_conventions.md §1 (relative links for every file referenced) and §2 (full-syntax for any /wb* command cited).
+4. End the report with:
+
+## 🧭 What's Next?
+
+Run `/wbNext <target_folder>` to get a current, ranked list of next actions (typically `/wbTest <target>` to verify the fix didn't regress anything else).

package/templates/commands/wbDeploy/wbDeploy_template.md

@@ -0,0 +1,224 @@
+# wbDeploy Template v2.1
+
+
+<!-- HELP_GATE_START -->
+## Help intercept (handle FIRST — before any other action)
+
+**If `$ARGUMENTS` contains `--help`, `-h`, or `--h`** (case-insensitive, anywhere in the args), DO NOT execute the command's normal procedure. Instead:
+
+1. Output the **HELP BLOCK** below verbatim (rendered as markdown).
+2. Stop. Do not perform any file reads, writes, or other tool calls.
+3. Do not generate any reports under `.wb/workflows/reports/`.
+
+Otherwise, ignore this section and proceed to the rest of the template.
+
+### HELP BLOCK — `/wbDeploy`
+
+## Three forms
+
+```
+/wbDeploy <app>                    # deploy to configured target (usually gh-pages)
+/wbDeploy <app> --dry-run          # preview, no push
+/wbDeploy <app> --target=local     # build + serve locally for testing
+```
+
+## The safe flow
+
+```
+/wbDeploy <app> --target=local     # build + preview locally
+# test in browser, confirm no prod-specific bugs
+/wbDeploy <app> --dry-run          # preview what would deploy
+/wbDeploy <app>                    # real deploy
+```
+
+Skipping the local step is the #1 cause of "works in dev, broken in prod" deploys.
+
+## Prerequisites
+
+The app must have `.wb/workflows/deploy.md` filled in with target, repo, branch, base-url. `/wbDeploy` refuses if missing.
+
+For GitHub Pages specifically, see [wbDeploy_github_pages_guide_claude](../wbDeploy_github_pages_guide_claude.md).
+
+## Gates the AI checks before deploy
+
+1. `/wbTest` must have passed recently. Failures BLOCK.
+2. `/wbAudit` BLOCKERS block. MAJORS are advisory.
+3. Build output is present (`dist/`).
+4. Deploy config is complete.
+
+If any gate fails, the command refuses with a specific fix.
+
+## After a successful deploy
+
+The AI tells you the live URL. **Open it.** The AI cannot verify the live site works — that's your job. Click around. Check the console. Refresh on a deep link.
+
+If the live site is broken but local-test passed, the issue is deploy-specific (base URL, CORS, DNS, GitHub Pages caching). Start with hard refresh + 5 min wait.
+
+## When to deploy
+
+- After `/wbAudit` on the app is clean.
+- After user-facing changes.
+- As part of a release cycle for apps bundled with package releases.
+- NOT after internal refactors nobody will see.
+- NOT for experimental changes. Create a scratch deploy target if needed.
+
+## When /wbDeploy is the wrong command
+
+- Package (code others import) → `/wbPublish`.
+- Just want to see your changes locally → `npm run dev`. That's different from `--target=local`.
+- Want to stage to a preview URL → set up a scratch deploy target in `deploy.md`, don't deploy to prod.
+
+> For deeper reading: [`docs_claude/commands/wbDeploy/wbDeploy_practical_claude.md`](../../docs/docs_claude/commands/wbDeploy/wbDeploy_practical_claude.md) (or the `_eli5_`, `_expert_`, `_examples_` siblings).
+
+<!-- FLAGS_TABLE_START -->
+## Flags & shortcuts
+
+Both forms are equivalent — pass either:
+
+| Long form | Shortcut |
+|---|---|
+| `--dry-run` | `-d` |
+| `--prod` | `-P` |
+| `--target` | `-t` |
+
+`-h` / `--help` / `--h` (any command) prints this help block instead of executing.
+## Self-correct mode (dual-mode invocation)
+
+```
+/wbDeploy <scope_folder>           # normal mode — produce a fresh output file
+/wbDeploy <previous_output_file>   # self-correct mode — verify & repair the file in place
+```
+
+When the first arg is an existing output file from a prior `/wbDeploy` run (detected by its first H1 — see this template's **Detection** section), the command runs in **verify-and-repair** mode: gap-fills missing fields, normalizes links, ticks done/valid checkboxes whose reports exist, never rewrites authored content. See [`../_shared/output_conventions.md`](../_shared/output_conventions.md) §3.
+
+<!-- FLAGS_TABLE_END -->
+<!-- HELP_GATE_END -->
+
+<!-- FLAG_NORMALIZE_START -->
+## Flag normalization (apply BEFORE parsing args)
+
+Before processing `$ARGUMENTS`, normalize these short-form flags to their long equivalents:
+
+- `-d` → `--dry-run`
+- `-P` → `--prod`
+- `-t` → `--target`
+
+The rest of this template documents only the long forms; the substitution above is the only place short forms are mentioned.
+<!-- FLAG_NORMALIZE_END -->
+
+
+
+> **How to use**: This is the manual template for orchestrating the deployment of consumer applications (e.g., demo sites, documentation) to web hosting platforms like Vercel, AWS, or a custom VPS.
+> **Read first:** [`../_shared/output_conventions.md`](../_shared/output_conventions.md) — applies to every cell of the output (relative links, full-syntax commands, self-correct mode).
+
+---
+
+## Detection (Self-Correct Mode)
+
+Trigger self-correct when the input file's first H1 matches:
+`# Deploy: <scope> — <YYYY-MM-DD>` *(or the legacy `# Deploy Entry #N` header).*
+
+Behavior is defined in [`../_shared/output_conventions.md`](../_shared/output_conventions.md) §3.
+
+Deploy-specific gap-fills:
+
+- Plain-text `.env.production`, build-output paths → relative markdown links per §1.
+- Bare deploy commands → full-syntax form per §2 where applicable.
+- Missing post-deploy smoke-test result → leave blank (do not fabricate).
+
+---
+
+## Filename & Folder Convention (v2 — Universal Daily File)
+
+**Path:** `<target_folder>/.wb/workflows/reports/<YYYY>/<MM>/<DD>/deployments/deploy_<target>_<YYYYMMDD>.md`
+
+> **No `<model>/` subfolder.** All models contribute to ONE deploy file per day per scope.
+> **No timestamp in filename.** Filename uses only the date.
+
+**Create-or-Append Rule:**
+- **File does NOT exist →** CREATE the file with a header and your deployment log as Entry #1.
+- **File ALREADY exists →** READ it, then APPEND as the next Entry #N.
+- **Every entry tagged:** `*(ModelName via Client — HH:MM)*`
+
+---
+
+## The Prompt (copy from here ↓)
+
+```
+━━━━━━━━━━━━━ /wbDeploy ━━━━━━━━━━━━━
+
+📁 TARGET APP: __TARGET_APP_PATH__
+📅 DATE: __TODAY__
+🤖 MODEL: __YOUR_MODEL_NAME__
+🖥️ CLIENT: __YOUR_CLIENT__
+🌐 ENVIRONMENT: __production_or_staging__
+
+━━━ CONTEXT & GOAL ━━━
+The user wants to deploy a physical application (e.g., documentation, demo site) to a web host (like wbc-ui.com or wbjs.net). Unlike library packages that go to NPM, this app must be built into static assets and pushed to a server/CDN.
+
+Your goal is to act as the DevOps Deployment Agent. You must ensure the app is synced with the latest library versions, build the application, and execute the deployment commands safely.
+
+━━━ INSTRUCTIONS ━━━
+
+**[TEMPORAL MEMORY]**: Before executing your main task, you MUST scan the `.wb/workflows/reports/` directory of your target scope. Look for recent `audits/`, `reviews/`, or `tests/` reports. Use these past reports to understand recent failures, technical debt, or architectural decisions that affect your current execution.
+
+
+1. **Infrastructure & DNS (If requested)**: Execute terminal commands to verify DNS propagation (`dig`, `ping`), configure server routing (e.g., Nginx virtual hosts), manage sub-domains, or provision SSL certificates (`certbot`).
+2. **Pre-Flight Sync**: Check if the app's `package.json` needs to be updated to use the latest public versions of `wb-core` or `wb-press2` (removing local `file:` links if it's a production deploy).
+3. **Environment Audit**: Verify that the correct environment variables (e.g., `.env.production`) are present for the target environment.
+4. **Build Execution**: Run the application-specific build script (e.g., `npm run build` inside the app folder).
+5. **Deploy Execution**: Provide or execute the specific deployment commands required for this app (e.g., `vercel --prod`, `rsync`, or FTP instructions).
+6. **Post-Deploy Smoke Test**: Define how the user can verify the deployment was successful (e.g., checking specific console logs on the live URL).
+7. SAVE using the Universal Daily File pattern:
+
+   CHECK if this file exists:
+   `<target_folder>/.wb/workflows/reports/__YYYY__/__MM__/__DD__/deployments/deploy___NAME_____YYYYMMDD__.md`
+
+   - If it does NOT exist → CREATE the file with header + your deployment log as Entry #1
+   - If it ALREADY exists → APPEND as the next Entry #N
+
+8. APPLY OUTPUT CONVENTIONS (see ../_shared/output_conventions.md):
+   - All file/folder references (env files, build outputs, host configs) → relative markdown links (§1).
+   - Any /wb* commands cited → full-syntax form (§2).
+
+9. END THE FILE WITH:
+
+   ## 🧭 What's Next?
+
+   Run `/wbNext <target_folder>` to get a current, ranked list of next actions (typically post-deploy verification or next-app deploy).
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+━━━ AUTO-APPEND FOOTER ━━━
+
+At the VERY END of the file (after "What's Next?"), you MUST append the `## 📂 Generated Files (__YYYYMMDD__)` cross-link footer. Do NOT use simple tables. You MUST use the rich "Tier 1" layout from `_shared/output_conventions.md` §5.
+
+Format required:
+```markdown
+---
+## 📂 Generated Files (__YYYYMMDD__)
+> Auto-appended per `_shared/output_conventions.md` §5. Same-level snapshot of top-level command outputs at write time.
+
+### 📚 Base Reference Files
+| Type | File | Description |
+|---|---|---|
+| Foundational | [context.md](../../../../../context.md) | Permanent Identity and Architecture (Source of Truth) |
+| Snapshot | [context_<scope>_<date>.md](../contexts/context_<scope>_<date>.md) | Daily snapshot used for current session context |
+| Foundational | [dev.md](../../../../../dev.md) | Permanent Development Commands and Status |
+
+### Global Files (`core2/` monorepo root)
+| Category | File | Source Command |
+|---|---|---|
+| Reports | [audit_core2_<date>.md](../../../../../../../../../../.wb/workflows/reports/<YYYY>/<MM>/<DD>/audits/audit_core2_<date>.md) | `/wbAudit core2/` |
+| Reports | [plan_core2_<date>.md](../../../../../../../../../../.wb/workflows/reports/<YYYY>/<MM>/<DD>/plans/plan_core2_<date>.md) | `/wbPlan core2/` |
+| Tracks | [track_core2_<date>.md](../../../../../../../../../../.wb/workflows/tracks/<YYYY>/<MM>/<DD>/track_core2_<date>.md) | `/wbTrack core2/` |
+
+<details>
+  <summary>📂 Sub-Package: [Active Package Name]</summary>
+
+| Category | File | Source Command |
+|---|---|---|
+| Reports | [audit_subpkg_<date>.md](../../../../../../../../../../apps/wb-core/subpkg/.wb/workflows/reports/<YYYY>/<MM>/<DD>/audits/audit_subpkg_<date>.md) | `/wbAudit` |
+
+</details>
+```
+```

package/templates/commands/wbDoc/wbDoc_template.md

@@ -0,0 +1,138 @@
+# /wbDoc: Execution Template
+
+
+<!-- HELP_GATE_START -->
+## Help intercept (handle FIRST — before any other action)
+
+**If `$ARGUMENTS` contains `--help`, `-h`, or `--h`** (case-insensitive, anywhere in the args), DO NOT execute the command's normal procedure. Instead:
+
+1. Output the **HELP BLOCK** below verbatim (rendered as markdown).
+2. Stop. Do not perform any file reads, writes, or other tool calls.
+3. Do not generate any reports under `.wb/workflows/reports/`.
+
+Otherwise, ignore this section and proceed to the rest of the template.
+
+### HELP BLOCK — `/wbDoc`
+
+## Two forms
+
+```
+/wbDoc <file>        # JSDoc on functions + inline comments
+/wbDoc <folder>      # README + JSDoc across the folder
+```
+
+## When to run
+
+- Before `/wbRelease` + `/wbPublish` — so npm users get current docs.
+- When adding a new public export (document it immediately, before consumers depend on undocumented behavior).
+- When `/wbAudit` flags missing JSDoc.
+- Monthly-ish on actively-edited packages — docs drift fast.
+
+## When *not* to run
+
+- On a file that `/wbAudit` flagged for refactor — docs will be stale in a week.
+- On internal helpers that aren't exported — documenting private is noise.
+- On boilerplate — `package.json`, `vite.config.js`, etc. don't need generated docs.
+
+## What good output looks like
+
+- JSDoc with `@param`, `@returns`, `@example`, and `@remarks` for gotchas.
+- Examples drawn from actual call sites, not invented.
+- Explicit mention of open architectural decisions when relevant.
+- Conventions from `dev.md` surfaced in the README (the `:wbCode="false"` rule, the `apiResponse_` cache, the `__WBC_PRO__` gate).
+
+## What bad output looks like
+
+- "This function takes a parameter" — restatement.
+- "Use this carefully" — vague warning without specifics.
+- Invented examples that don't match any real usage.
+- Examples missing the `:wbCode="false"` you always apply.
+
+If you see any of these, re-prompt: *"ground examples in actual call sites. Name the project-specific conventions. Drop generic prose."*
+
+## The context.md sync
+
+After `/wbDoc`, check that `context.md` API section matches what you just documented. If they disagree, pick one and fix the other — they should always agree.
+
+## When /wbDoc is the wrong command
+
+- Code review → `/wbAudit`.
+- Finding dead code → `/wbClean`.
+- Understanding how something works → read the code or `/wbContext --focus=<x>`.
+- Writing user-facing marketing copy → `/wbBroadcast`, not `/wbDoc`.
+
+> For deeper reading: [`docs_claude/commands/wbDoc/wbDoc_practical_claude.md`](../../docs/docs_claude/commands/wbDoc/wbDoc_practical_claude.md) (or the `_eli5_`, `_expert_`, `_examples_` siblings).
+
+<!-- FLAGS_TABLE_START -->
+## Flags & shortcuts
+
+Both forms are equivalent — pass either:
+
+| Long form | Shortcut |
+|---|---|
+| `--focus` | `-f` |
+
+`-h` / `--help` / `--h` (any command) prints this help block instead of executing.
+## Self-correct mode (dual-mode invocation)
+
+```
+/wbDoc <scope_folder>           # normal mode — produce a fresh output file
+/wbDoc <previous_output_file>   # self-correct mode — verify & repair the file in place
+```
+
+When the first arg is an existing output file from a prior `/wbDoc` run (detected by its first H1 — see this template's **Detection** section), the command runs in **verify-and-repair** mode: gap-fills missing fields, normalizes links, ticks done/valid checkboxes whose reports exist, never rewrites authored content. See [`../_shared/output_conventions.md`](../_shared/output_conventions.md) §3.
+
+<!-- FLAGS_TABLE_END -->
+<!-- HELP_GATE_END -->
+
+<!-- FLAG_NORMALIZE_START -->
+## Flag normalization (apply BEFORE parsing args)
+
+Before processing `$ARGUMENTS`, normalize these short-form flags to their long equivalents:
+
+- `-f` → `--focus`
+
+The rest of this template documents only the long forms; the substitution above is the only place short forms are mentioned.
+<!-- FLAG_NORMALIZE_END -->
+
+
+
+**ROLE:** The Scribe
+**TARGET:** The provided file or folder.
+**Read first:** [`../_shared/output_conventions.md`](../_shared/output_conventions.md) — applies to the summary report (relative links, full-syntax commands, self-correct mode).
+
+---
+
+## ━━━ DETECTION (Self-Correct Mode) ━━━
+
+Trigger self-correct when the input file's first H1 matches:
+`# Doc: <scope> — <YYYY-MM-DD>` *(if a report file is produced).*
+
+Behavior is defined in [`../_shared/output_conventions.md`](../_shared/output_conventions.md) §3.
+
+Doc-specific gap-fills:
+
+- Plain-text mentions of documented files → relative markdown links per §1.
+- Bare `/wbReview` cited → full-syntax `/wbReview <target>` per §2.
+
+---
+
+## ━━━ OBJECTIVE ━━━
+Your job is to document the code beautifully. **CRITICAL RULE:** You are forbidden from modifying any functional logic, variable names, or architecture. Your only output must be comments and markdown files.
+
+## ━━━ PHASE 1: DISCOVERY ━━━
+1. Read the target code to understand its purpose, inputs, and outputs.
+2. Cross-reference with `context.md` to understand the broader package context.
+
+## ━━━ PHASE 2: INJECTION ━━━
+1. **For Files:** Inject professional JSDoc/TSDoc comments above every major class, function, and complex logic block. Explain *why* it does something, not just *what* it does.
+2. **For Folders:** Generate or update a comprehensive `README.md` explaining the module's purpose, usage examples, and API surface.
+
+## ━━━ PHASE 3: REPORT ━━━
+Provide a brief summary of what files were documented. Apply output_conventions.md §1 (relative links for every documented file) and §2 (full-syntax for any /wb* command cited).
+
+End the report with:
+
+## 🧭 What's Next?
+
+Run `/wbNext <target_folder>` to get a current, ranked list of next actions (typically `/wbReview <target>` to validate doc accuracy, or `/wbDeploy` if the docs are user-facing).

package/templates/commands/wbExplain/wbExplain_template.md

@@ -0,0 +1,98 @@
+<!-- HELP_GATE_START -->
+# `/wbExplain` Command
+**Role:** The Teacher / The Architect
+**Purpose:** Generate persistent, formatted explanations for a specific task ID, a codebase architecture, or a general technical question, without executing code changes.
+**Usage:** `/wbExplain <target> "<query>|<column_filter>|*" [--as=<style>]`
+**Example (Task):** `/wbExplain plan_core2_20260503.md --id=1 --as=eli5`
+**Example (Batch):** `/wbExplain packages/wb-core/ * --as=expert,it`
+**Example (Filter):** `/wbExplain plan_core2_20260503.md --est<=30 --as=expert`
+**Example (General):** `/wbExplain packages/wb-core/ "How does the Tier parser work?" --as=expert`
+<!-- HELP_GATE_END -->
+
+━━━ TRIGGER & GOAL ━━━
+
+You have been invoked to run `/wbExplain`. Your job is to deeply analyze the requested topic or task/idea ID, and generate a clear, pedagogical markdown explanation file. You MUST NOT execute the task or modify source code.
+> **Batch Processing (`*` or column filter):** If the user passes `*` or a column filter (e.g., `--est<=30`, `--p=P1`), you must locate the active `plan_*.md` or `idea_*.md` file for the target, identify ALL matching outstanding items, and generate a separate details file for *each* matching item sequentially, auto-linking all of them.
+
+━━━ MODE DETECTION ━━━
+
+Detect the operating mode from the target:
+
+- **Plan scope** (target is `plan_*.md` or `--id=N` without `--scope=idea`): Standard task explanation mode.
+- **Idea scope** (target is `idea_*.md` or `--scope=idea` flag is present): Idea explanation mode — explains *why* the idea matters, *what* it would change, and *how* it could be approached.
+
+━━━ DETECTION & SMART MERGE ━━━
+
+If the user runs this command multiple times for the same topic/task on the same day, you MUST NOT create a new file (e.g. do not create `task_1_details_fr_ar.md`). Instead, use the **Smart Merge Protocol**:
+Open the existing details/explanation file and **APPEND** your new translation or new explanation style directly below the existing `Deep Dive` or `Recommended Approach` sections, right before the `## 🧭 What's Next?` footer. Never fragment the knowledge into multiple daily files for the same task.
+
+━━━ FLAGS & STYLES ━━━
+
+If the user includes `--as=<style>` (e.g., `--as=eli5`, `--as=expert`, `--as=technical`), you MUST adopt that exact tone from `../../shortcuts/shortcuts.md`.
+
+# ━━━ OUTPUT FORMAT ━━━
+
+1. **Generate the File:**
+   - **Task-mode** (explaining a specific Task ID from a plan): Create at `<target_folder>/.wb/workflows/reports/<YYYY>/<MM>/<DD>/plans/tasks/task_<N>/task_<N>_details_<scope>_<YYYYMMDD>.md`. Create the `task_<N>/` folder if it does not exist.
+   - **Idea-mode** (explaining a specific Idea ID from an idea file): Create at `<target_folder>/.wb/workflows/reports/<YYYY>/<MM>/<DD>/ideas/ideas_reports/idea_<N>/idea_<N>_details_<scope>_<YYYYMMDD>.md`. Create the `idea_<N>/` folder if it does not exist.
+   - **Free-text mode** (general question, no task/idea ID): Create at `<target_folder>/.wb/workflows/reports/<YYYY>/<MM>/<DD>/plans/explanations/explain_<slug>_<YYYYMMDD>.md`. Create the `explanations/` folder if it does not exist.
+   Do not output code blocks containing the entire codebase.
+
+2. **Auto-Link in Source File:** If you generated an explanation for a specific task or idea ID, you MUST locate the active source file (`plan_*.md` or `idea_*.md`). Find the row for your ID and upgrade the `🔗` column.
+   - **Plan file:** If the column holds the inactive placeholder `<span title="...">📄</span>`, replace it with an active markdown link containing the `--as` tags: `[📄 expert,fr](tasks/task_<N>/task_<N>_details_<scope>_<YYYYMMDD>.md "View Details")`.
+   - **Idea file:** Same pattern but routed to: `[📄 expert](ideas_reports/idea_<N>/idea_<N>_details_<scope>_<YYYYMMDD>.md "View Details")`.
+   - If the column already has an active link, append your new tags to the existing list.
+
+# Explanation: <target_folder_name> — <YYYY-MM-DD>
+
+---
+
+## 💻 Run: `/wbExplain <target> "<query>|--id=N" [--as=<style>]` *(HH:MM)*
+> **Model:** <model_name>
+> **Client:** <client_name>
+
+### 1. High-Level Summary
+(One paragraph answering the core question or explaining the task).
+
+### 2. Deep Dive
+(Break down the issue, architecture, or task step-by-step).
+
+### 3. Recommended Approach (If applicable)
+(If explaining a task, how should the worker approach it? If explaining a bug, what is the fix?)
+
+## 🧭 What's Next?
+If this was a task explanation, recommend the exact `/wbWork` command to execute it now. Otherwise, suggest `/wbNext`.
+
+━━━ AUTO-APPEND FOOTER ━━━
+
+At the VERY END of the file (after "What's Next?"), you MUST append the `## 📂 Generated Files (__YYYYMMDD__)` cross-link footer. Do NOT use simple tables. You MUST use the rich "Tier 1" layout from `_shared/output_conventions.md` §5.
+
+Format required:
+```markdown
+---
+## 📂 Generated Files (__YYYYMMDD__)
+> Auto-appended per `_shared/output_conventions.md` §5. Same-level snapshot of top-level command outputs at write time.
+
+### 📚 Base Reference Files
+| Type | File | Description |
+|---|---|---|
+| Foundational | [context.md](../../../../../context.md) | Permanent Identity and Architecture (Source of Truth) |
+| Snapshot | [context_<scope>_<date>.md](../contexts/context_<scope>_<date>.md) | Daily snapshot used for current session context |
+| Foundational | [dev.md](../../../../../dev.md) | Permanent Development Commands and Status |
+
+### Global Files (`core2/` monorepo root)
+| Category | File | Source Command |
+|---|---|---|
+| Reports | [audit_core2_<date>.md](../../../../../../../../../../.wb/workflows/reports/<YYYY>/<MM>/<DD>/audits/audit_core2_<date>.md) | `/wbAudit core2/` |
+| Reports | [plan_core2_<date>.md](../../../../../../../../../../.wb/workflows/reports/<YYYY>/<MM>/<DD>/plans/plan_core2_<date>.md) | `/wbPlan core2/` |
+| Tracks | [track_core2_<date>.md](../../../../../../../../../../.wb/workflows/tracks/<YYYY>/<MM>/<DD>/track_core2_<date>.md) | `/wbTrack core2/` |
+
+<details>
+  <summary>📂 Sub-Package: [Active Package Name]</summary>
+
+| Category | File | Source Command |
+|---|---|---|
+| Reports | [audit_subpkg_<date>.md](../../../../../../../../../../apps/wb-core/subpkg/.wb/workflows/reports/<YYYY>/<MM>/<DD>/audits/audit_subpkg_<date>.md) | `/wbAudit` |
+
+</details>
+```