@dv.nghiem/flowdeck 0.1.0

package/docs/intelligence.md

@@ -0,0 +1,294 @@
+# FlowDeck Intelligence Features
+
+FlowDeck's intelligence layer adds safety-first AI editing, persistent architecture memory, and risk prediction directly into every OpenCode session. These features require no extra setup beyond running `/fd-new-project`.
+
+---
+
+## Overview
+
+| Feature | Command / Hook | Storage |
+|---------|---------------|---------|
+| Change Impact Radar | `/fd-impact-radar` | VOLATILITY.json, MEMORY.json |
+| Patch Trust Score | Hook (automatic) | VOLATILITY.json, FAILURES.json |
+| Blast Radius Preview | `/fd-blast-radius` | MEMORY.json, FAILURES.json |
+| Repo Memory Graph | `repo-memory` tool | `.codebase/MEMORY.json` |
+| Failure Replay Engine | `failure-replay` tool | `.codebase/FAILURES.json` |
+| Safe Execution Modes | Hook (automatic) | `.planning/config.json` |
+| Test Gap Detector | `/fd-test-gap` | VOLATILITY.json |
+| Architectural Constraint Guard | Hook (automatic) | `.codebase/CONSTRAINTS.md` |
+| Intent-to-Change Translator | `/fd-translate-intent` | — |
+| Confidence-Aware Planning | Skill | — |
+| Codebase Volatility Map | `/fd-volatility-map`, `volatility-map` tool | `.codebase/VOLATILITY.json` |
+| Human Review Routing | `/fd-review-route` | VOLATILITY.json, FAILURES.json |
+| Regression Prediction | `/fd-regression-predict` | — |
+| Decision Trace | `decision-trace` tool + hook | `.codebase/DECISIONS.jsonl` |
+| Self-Healing Policies | `policy-engine` tool | `.codebase/POLICIES.json` |
+
+---
+
+## Slash Commands
+
+### `/fd-impact-radar`
+
+Predicts which files, modules, APIs, tests, and database paths are likely to be affected before the AI edits anything.
+
+```
+/fd-impact-radar --change "refactor auth token handling" --scope all
+/fd-impact-radar --change "drop users table" --json
+```
+
+**Arguments:**
+- `--change` — describe the proposed change (free text)
+- `--scope` — `all` (default), `api`, `db`, `tests`
+- `--json` — machine-readable JSON output
+
+**Output:** Table showing researcher/architect/tester agent roles, known hotspots, and recommended traversal scope.
+
+---
+
+### `/fd-blast-radius`
+
+Shows the likely downstream consequences of a proposed change — hidden dependencies, fragile integration points, and predicted test breakages.
+
+```
+/fd-blast-radius --change "delete legacy session table" --depth 3
+```
+
+**Arguments:**
+- `--change` — describe the proposed change
+- `--depth` — dependency traversal hops (default: `2`)
+- `--json` — JSON output
+
+**How it works:** Reads Repo Memory Graph for dependency edges. Cross-references recurring failure patterns from Failure Replay Engine. Spawns architect + researcher + tester agent team.
+
+---
+
+### `/fd-translate-intent`
+
+Converts a vague request like "make checkout faster" into concrete, ranked implementation options with tradeoffs **before** any code is written.
+
+```
+/fd-translate-intent --intent "make checkout faster"
+/fd-translate-intent --intent "reduce memory usage on the worker"
+```
+
+**Arguments:**
+- `--intent` — the high-level intent to translate (required)
+- `--json` — JSON output
+
+---
+
+### `/fd-volatility-map`
+
+Displays the Codebase Volatility Map — highlights unstable zones based on churn, hotfix frequency, and unresolved TODO clusters.
+
+```
+/fd-volatility-map
+/fd-volatility-map --threshold volatile --limit 10
+```
+
+**Arguments:**
+- `--threshold` — minimum stability level to show: `stable`, `moderate`, `volatile` (default), `critical`
+- `--limit` — max results
+- `--json` — JSON output
+
+**Populated by:** `/fd-map-codebase` writes initial data; the `volatility-map` tool allows incremental updates.
+
+---
+
+### `/fd-regression-predict`
+
+Estimates the most likely regression categories for a change — performance, auth, schema, UI states, async flows, etc.
+
+```
+/fd-regression-predict --change "add webhook retry logic" --categories all
+```
+
+**Arguments:**
+- `--change` — describe the proposed change
+- `--categories` — comma-separated from: `performance`, `auth`, `schema`, `ui-state`, `async-flow`, `api-contract`, `data-integrity`, `security`, `config`, `i18n` (default: `all`)
+- `--json` — JSON output
+
+---
+
+### `/fd-test-gap`
+
+Identifies which areas of a proposed change are weakly covered by tests, and suggests the minimum high-value tests to add first.
+
+```
+/fd-test-gap --change "add payment webhook handler"
+/fd-test-gap --change "update user schema" --scope unit
+```
+
+**Arguments:**
+- `--change` — describe the proposed change
+- `--scope` — `unit`, `integration`, `e2e`, `all` (default)
+- `--json` — JSON output
+
+---
+
+### `/fd-review-route`
+
+Routes risky patches to the right reviewer type — security, backend, infra, domain-owner, frontend, data, or devops — based on the file paths and change description.
+
+```
+/fd-review-route --files "src/auth/token.ts,src/api/routes.ts" --change "new JWT rotation logic"
+```
+
+**Arguments:**
+- `--files` — comma-separated file paths being changed
+- `--change` — describe the change
+- `--json` — JSON output
+
+**Routing rules:**
+- `security` — auth, token, password, crypto, JWT, RBAC, XSS, SQL keywords; always added for high-risk patches
+- `backend` — API, route, controller, migration keywords
+- `infra` — Docker, Kubernetes, Terraform, CI/CD keywords
+- `domain-owner` — billing, payment, checkout, subscription keywords
+- `frontend` — component, CSS, React, Vue keywords
+- `data` — schema, migration, index, constraint keywords
+- `devops` — pipeline, YAML workflow, cron, schedule keywords
+
+---
+
+## Automatic Hooks
+
+These run on every `write` or `edit` tool call with no manual trigger needed.
+
+### Patch Trust Score
+
+Every AI-generated write/edit is scored 0–100:
+
+| Score | Verdict | Action |
+|-------|---------|--------|
+| ≥ 80 | `safe` | Auto-apply |
+| 40–79 | `review-required` | Logged with signals |
+| < 40 | `high-risk` | Warning printed, human review required |
+
+**Risk signals checked:**
+- File is in a `critical` volatility zone (−40 pts)
+- File is in a `volatile` zone (−25 pts)
+- File has moderate churn (−10 pts)
+- File has prior failure history in FAILURES.json (−20 pts)
+- Edit content contains high-risk keywords: password, secret, token, auth, crypto, jwt, etc. (−8 pts each, max −30 pts)
+
+### Safe Execution Modes
+
+Automatically selects the editing mode for the session:
+
+| Mode | When Used |
+|------|-----------|
+| `auto-edit` | Trust score ≥ 60, low volatility |
+| `guarded` | Trust score 30–59, or moderate volatility |
+| `review-only` | Trust score < 30, or config override |
+
+Override by setting `execution_mode` in `.planning/config.json`:
+```json
+{ "execution_mode": "review-only" }
+```
+
+### Architectural Constraint Guard
+
+Before any write or edit, FlowDeck reads `.codebase/CONSTRAINTS.md` and blocks writes to any path listed under `## Forbidden Paths`.
+
+**Example `.codebase/CONSTRAINTS.md`:**
+```markdown
+## Forbidden Paths
+- src/legacy/
+- infra/production/
+- db/migrations/
+```
+
+### Decision Trace Hook
+
+Every write or edit automatically appends a minimal entry to `.codebase/DECISIONS.jsonl` recording the tool name, file path, and timestamp. For full entries with rationale, use the `decision-trace` tool explicitly.
+
+---
+
+## Persistent State Tools
+
+These tools manage the `.codebase/` directory and can be called directly by agents.
+
+### `repo-memory`
+
+Manages `.codebase/MEMORY.json` — a persistent graph of modules, services, APIs, schemas, and their relationships.
+
+**Actions:** `read`, `write_node`, `query`, `delete_node`
+
+**Example:**
+```
+repo-memory action=write_node node_id=auth-module node={type:module, path:src/auth, owner:alice, tags:[auth,security], ...}
+repo-memory action=query query={type:module, owner:alice}
+```
+
+### `failure-replay`
+
+Manages `.codebase/FAILURES.json` — a log of reverted commits, failed deployments, flaky tests, and bug fixes.
+
+**Actions:** `record`, `query`, `list`, `mark_resolved`
+
+**Example:**
+```
+failure-replay action=record entry={id:deploy-001, type:failed_deployment, description:"...", affected_paths:[src/auth], tags:[auth]}
+failure-replay action=query query={path_prefix:src/auth}
+```
+
+### `decision-trace`
+
+Manages `.codebase/DECISIONS.jsonl` — append-only log of why every change was made.
+
+**Actions:** `record`, `query`, `get_for_file`
+
+**Fields:** `file_path`, `change_type`, `rationale`, `evidence[]`, `assumptions[]`, `alternatives_considered[]`, `risk_level`
+
+### `volatility-map`
+
+Manages `.codebase/VOLATILITY.json` — per-file churn and stability data.
+
+**Actions:** `read`, `write`, `query_hotspots`, `update_entry`
+
+**Stability labels:** `stable` → `moderate` → `volatile` → `critical` (computed from churn score + hotfix count + TODO count)
+
+### `policy-engine`
+
+Manages `.codebase/POLICIES.json` — self-healing editing rules that update after repeated failures.
+
+**Actions:** `list`, `add`, `record_violation`, `toggle`, `query`
+
+---
+
+## `.codebase/` File Reference
+
+| File | Format | Purpose |
+|------|--------|---------|
+| `MEMORY.json` | JSON | Repo architecture graph (nodes + edges) |
+| `FAILURES.json` | JSON | Failure history and recurrence tracking |
+| `DECISIONS.jsonl` | Newline-delimited JSON | Append-only edit rationale log |
+| `VOLATILITY.json` | JSON | Per-file churn and stability metrics |
+| `POLICIES.json` | JSON | Self-healing editing rule set |
+| `CONSTRAINTS.md` | Markdown | Forbidden path list for Arch Constraint Guard |
+
+> **Tip:** All `.codebase/` files should be committed to version control so the intelligence layer improves over time.
+
+---
+
+## Skills
+
+Each intelligence feature also has a corresponding skill that gives the OpenCode agent detailed workflow instructions. Skills are installed automatically by `install.sh`.
+
+| Skill | Name |
+|-------|------|
+| `change-impact-radar` | Change Impact Radar |
+| `patch-trust-score` | Patch Trust Score |
+| `blast-radius-preview` | Blast Radius Preview |
+| `repo-memory-graph` | Repo Memory Graph |
+| `failure-replay-engine` | Failure Replay Engine |
+| `test-gap-detector` | Test Gap Detector |
+| `arch-constraint-guard` | Architectural Constraint Guard |
+| `intent-translator` | Intent-to-Change Translator |
+| `confidence-aware-planning` | Confidence-Aware Planning |
+| `volatility-map` | Codebase Volatility Map |
+| `human-review-routing` | Human Review Routing |
+| `regression-prediction` | Regression Prediction |
+| `decision-trace` | Decision Trace |
+| `self-healing-policies` | Self-Healing Prompt Policies |

package/docs/multi-repo.md

@@ -0,0 +1,201 @@
+# Multi-Repo & Microservices
+
+FlowDeck supports coordinating changes across multiple repositories in a microservice architecture. The `@multi-repo-coordinator` agent manages dependency graphs, determines change order, and produces per-repo CHANGE PLANs.
+
+---
+
+## When to Use Multi-Repo Mode
+
+Multi-repo mode is appropriate when:
+
+- A shared API contract is changing and multiple services need to update their clients
+- A breaking change requires a coordinated rollout with a specific service order
+- A new cross-cutting capability (authentication, distributed tracing, audit logging) must be added to several services at once
+- Dependency upgrades need to be applied consistently across a service mesh
+
+Single-repo mode is sufficient for all other work. Multi-repo coordination adds overhead — only enable it when the cross-repo dependency is real.
+
+---
+
+## Setup
+
+### Step 1 — Initialize the root repository
+
+If your root (orchestrating) repository is not already a FlowDeck project:
+
+```
+/fd-new-project MyPlatform
+```
+
+This creates `.planning/` and `.planning/config.json` in the root repo.
+
+### Step 2 — Register service repositories
+
+```
+/fd-multi-repo --add ../user-service upstream-api
+/fd-multi-repo --add ../order-service consumer
+/fd-multi-repo --add ../notification-service consumer
+/fd-multi-repo --add ../api-gateway edge
+```
+
+Each `--add` command:
+1. Resolves and validates the path
+2. Detects the tech stack (language, framework) from the target repo's files
+3. Appends an entry to `sub_repos` in `.planning/config.json`
+
+### Step 3 — Verify registration
+
+```
+/fd-multi-repo --list
+```
+
+Expected output:
+
+```
+Registered repositories:
+  user-service       ../user-service         role: upstream-api    tech: node+typescript
+  order-service      ../order-service        role: consumer        tech: node+typescript
+  notification-svc   ../notification-service  role: consumer        tech: python
+  api-gateway        ../api-gateway          role: edge            tech: golang
+```
+
+---
+
+## config.json sub_repos Schema
+
+Registered repos are stored in `.planning/config.json` under the `sub_repos` key:
+
+```json
+{
+  "sub_repos": [
+    {
+      "name": "user-service",
+      "path": "../user-service",
+      "role": "upstream-api",
+      "tech_stack": "node+typescript",
+      "owner_team": "platform"
+    },
+    {
+      "name": "order-service",
+      "path": "../order-service",
+      "role": "consumer",
+      "tech_stack": "node+typescript",
+      "owner_team": "commerce"
+    },
+    {
+      "name": "notification-service",
+      "path": "../notification-service",
+      "role": "consumer",
+      "tech_stack": "python",
+      "owner_team": "growth"
+    },
+    {
+      "name": "api-gateway",
+      "path": "../api-gateway",
+      "role": "edge",
+      "tech_stack": "golang",
+      "owner_team": "platform"
+    }
+  ]
+}
+```
+
+All fields except `owner_team` are required. `owner_team` is optional but recommended — it enables `@multi-repo-coordinator` to surface team-level communication needs in the CHANGE PLAN.
+
+---
+
+## Role Vocabulary
+
+The `role` field tells `@multi-repo-coordinator` how each service fits into the dependency graph. It uses this to determine change order and to classify changes as breaking or non-breaking.
+
+| Role | Meaning |
+|------|---------|
+| `upstream-api` | Exposes an API that other services consume. Changes here propagate outward. |
+| `consumer` | Calls one or more upstream APIs. Must update its client when upstream contracts change. |
+| `edge` | API gateway or entry point. Routes external traffic and may enforce rate limits or authentication. |
+| `shared-lib` | A library imported by other services. Breaking changes here affect every consumer simultaneously. |
+| `worker` | Background job processor. Typically a consumer of events or queues; rarely an upstream dependency. |
+| `data-store` | Database, cache, or storage service. Schema changes here can be breaking for any direct consumer. |
+
+---
+
+## Running a Cross-Repo Change
+
+Invoke `@multi-repo-coordinator` with a plain-language description of the cross-cutting change:
+
+```
+@multi-repo-coordinator I need to add user preferences to the user-service API and
+update all consumer services to use the new endpoint.
+```
+
+### What `@multi-repo-coordinator` does
+
+1. **Reads `sub_repos`** from `.planning/config.json` to identify all registered services
+2. **Builds the dependency graph** — in the example above: `user-service → order-service`, `user-service → notification-service`, and `api-gateway → user-service`
+3. **Determines change order** based on roles: upstream services change first, consumers second, edge last
+4. **Classifies the change**: adding a new field or endpoint is non-breaking; renaming or removing is breaking. Breaking changes require a compatibility strategy (versioned endpoints, feature flags, or synchronized cutover)
+5. **Produces a CHANGE PLAN** for each affected repository in dependency order
+
+---
+
+## CHANGE PLAN Format
+
+`@multi-repo-coordinator` produces a CHANGE PLAN that is saved to `.planning/fd-multi-repo/CHANGE-<timestamp>.md`:
+
+```
+CHANGE PLAN — user-preferences feature
+
+Order of changes:
+  1. user-service (upstream-api)   — add GET /users/{id}/preferences endpoint
+  2. order-service (consumer)      — update UserClient to call new preferences endpoint
+  3. notification-service (consumer) — update notification triggers with user preferences
+  4. api-gateway (edge)            — add /preferences route, update rate limit policy
+
+Breaking changes: None (additive endpoint — existing clients unaffected)
+Rollout strategy: canary → staging → production per service in the order above
+
+Owner teams notified:
+  platform (user-service, api-gateway)
+  commerce (order-service)
+  growth (notification-service)
+```
+
+For breaking changes, the CHANGE PLAN includes a compatibility section:
+
+```
+Breaking changes: YES — /users/{id} response shape modified (field renamed)
+Compatibility strategy:
+  - Deploy user-service@v2 alongside v1 (parallel run)
+  - Migrate consumers to v2 endpoint one-by-one
+  - Deprecate v1 after all consumers are migrated (target: 2 sprints)
+  - Remove v1 after deprecation window closes
+```
+
+---
+
+## Multi-Repo Workflow
+
+The `multi-repo-flow` workflow orchestrates the full end-to-end process:
+
+1. **Analyze** — `@code-explorer` runs in each registered repo and builds a combined dependency graph
+2. **Classify** — `@multi-repo-coordinator` identifies which changes are breaking vs non-breaking and determines service change order
+3. **Plan** — produces a CHANGE PLAN per repo in dependency order
+4. **Execute** — `@coder` is invoked per repo in order; `@tester` runs per repo in parallel with `@coder` (using that repo's test suite)
+5. **Verify** — `@reviewer` and `@security-auditor` run per repo after implementation; integration tests are run across the full service mesh in staging before any production rollout
+
+Each step produces output files in `.planning/fd-multi-repo/` so the entire process is auditable.
+
+---
+
+## Multi-Repo Commands Reference
+
+| Command | What it does |
+|---------|-------------|
+| `/fd-multi-repo --add <path> <role>` | Register a repo with the given path and role |
+| `/fd-multi-repo --list` | Print a table of all registered repos |
+| `/fd-multi-repo --status` | Show `git status` summary for every registered repo |
+| `/fd-multi-repo --remove <name>` | Remove a repo from `sub_repos` by name |
+
+---
+
+← [Back to Index](index.md)

package/docs/notifications.md

@@ -0,0 +1,170 @@
+# System Notifications
+
+FlowDeck fires desktop notifications when commands that require your attention complete. This is useful when you switch to another application while the AI processes a task — you will be alerted when your input is needed or when a long-running command is ready for review.
+
+---
+
+## How It Works
+
+When an interactive command finishes (one that either asks questions or produces output you need to approve), FlowDeck sends a desktop notification through the OS notification system. Notification urgency depends on the command:
+
+- **Critical-level (urgent):** `/fd-discuss`, `/fd-plan`, `/fd-review-code`, `/fd-deploy-check`, `/fd-new-project`  
+  These commands present questions or decisions that block further progress. The notification is sent at high urgency so it appears even in Do Not Disturb mode on some systems.
+
+- **Info-level:** `/fd-new-feature`, `/fd-fix-bug`, `/fd-write-docs`, `/fd-checkpoint`  
+  These commands complete autonomously and notify you that output is ready for review. Low urgency — appears in notification center but does not interrupt focus.
+
+Notifications are **best-effort**: if the notification system is unavailable (missing package, SSH session without display, headless CI), FlowDeck logs a warning and continues silently. No command is blocked by a notification failure.
+
+---
+
+## Linux (`notify-send`)
+
+FlowDeck uses `notify-send` from the `libnotify` package. A desktop session (X11 or Wayland) must be active.
+
+### Installation
+
+```bash
+# Debian / Ubuntu
+sudo apt install libnotify-bin
+
+# Fedora / RHEL / CentOS Stream
+sudo dnf install libnotify
+
+# Arch Linux
+sudo pacman -S libnotify
+```
+
+### Verify
+
+```bash
+notify-send "FlowDeck" "Notifications working"
+```
+
+A toast notification should appear in the top-right corner of your desktop (or wherever your notification daemon places them — GNOME, KDE, and sway all position them differently).
+
+---
+
+## macOS (`osascript`)
+
+`osascript` is a standard macOS tool available on every installation. No additional packages are needed.
+
+### Allow notifications from Terminal
+
+macOS requires per-application notification permission:
+
+1. Open **System Preferences** (macOS 12 and earlier) or **System Settings** (macOS 13+)
+2. Navigate to **Notifications**
+3. Find **Terminal** in the app list (or your OpenCode host application if you run it outside Terminal)
+4. Set **Allow Notifications** to on
+5. Choose **Alerts** or **Banners** depending on your preference
+
+### Verify
+
+```bash
+osascript -e 'display notification "Notifications working" with title "FlowDeck"'
+```
+
+---
+
+## Windows (PowerShell toast)
+
+FlowDeck uses the `Windows.UI.Notifications` WinRT API via PowerShell. This requires Windows 10 or later and PowerShell 5 or later. No additional installation is needed.
+
+### Allow notifications from PowerShell
+
+1. Open **Settings → System → Notifications**
+2. Scroll to the app list and find **Windows PowerShell**
+3. Enable notifications for Windows PowerShell
+
+### Verify
+
+```powershell
+[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] | Out-Null
+$template = [Windows.UI.Notifications.ToastNotificationManager]::GetTemplateContent(
+    [Windows.UI.Notifications.ToastTemplateType]::ToastText02)
+$template.SelectSingleNode("//text[@id='1']").InnerText = "FlowDeck"
+$template.SelectSingleNode("//text[@id='2']").InnerText = "Notifications working"
+$toast = [Windows.UI.Notifications.ToastNotification]::new($template)
+[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier("FlowDeck").Show($toast)
+```
+
+---
+
+## Notification Content Reference
+
+| Command | Title | Body |
+|---------|-------|------|
+| `/fd-discuss` | `FlowDeck: /fd-discuss` | Your input is needed — please check OpenCode |
+| `/fd-plan` | `FlowDeck: /fd-plan` | Your input is needed — please check OpenCode |
+| `/fd-review-code` | `FlowDeck: /fd-review-code` | Your input is needed — please check OpenCode |
+| `/fd-deploy-check` | `FlowDeck: /fd-deploy-check` | Your input is needed — please check OpenCode |
+| `/fd-new-project` | `FlowDeck: /fd-new-project` | Your input is needed — please check OpenCode |
+| `/fd-new-feature` | `FlowDeck: /fd-new-feature complete` | Review the output and choose your next step |
+| `/fd-fix-bug` | `FlowDeck: /fd-fix-bug complete` | Review the output and choose your next step |
+| `/fd-write-docs` | `FlowDeck: /fd-write-docs complete` | Review the output and choose your next step |
+| `/fd-checkpoint` | `FlowDeck: /fd-checkpoint` | State saved — safe to close this session |
+
+---
+
+## Disabling Notifications
+
+Notifications are opt-out at the OS level. To stop receiving them:
+
+- **Linux:** Uninstall `libnotify-bin` (`sudo apt remove libnotify-bin`) or close your notification daemon
+- **macOS:** System Settings → Notifications → find Terminal → set Allow Notifications to off
+- **Windows:** Settings → System → Notifications → Windows PowerShell → toggle off
+
+Alternatively, when FlowDeck runs in a non-interactive environment (CI pipeline, headless server, SSH session without `$DISPLAY`) it detects the absence of a notification system and skips notification dispatch automatically. No configuration is needed for headless use.
+
+---
+
+## Troubleshooting
+
+### Linux: notifications not appearing
+
+**`notify-send` command not found:**
+```bash
+which notify-send   # should return a path
+sudo apt install libnotify-bin
+```
+
+**`notify-send` runs but nothing appears:**
+```bash
+echo $DISPLAY   # must not be empty; e.g. :0 or :1
+```
+
+If `$DISPLAY` is empty, you are in a session that is not connected to a display server. Set it explicitly if you are connected to a local machine via SSH:
+```bash
+export DISPLAY=:0
+notify-send "test" "test"
+```
+
+**Running under Wayland:**
+```bash
+echo $WAYLAND_DISPLAY   # should be wayland-0 or similar
+```
+
+Some distributions require `notify-send` version 0.8+ for Wayland support. Check: `notify-send --version`.
+
+---
+
+### macOS: notifications not appearing
+
+1. Run the verification command above — if it shows no notification, Terminal notifications are disabled
+2. Check System Settings → Notifications → Terminal → Allow Notifications is on
+3. Check that **Focus** or **Do Not Disturb** is not suppressing alerts
+4. On macOS 14+, check that notification permissions have not been reset after an OS update
+
+---
+
+### Windows: notifications not appearing
+
+1. Verify Settings → System → Notifications → **Notifications** master toggle is on
+2. Verify **Windows PowerShell** is enabled in the app-level list
+3. Check that **Focus Assist** is not set to **Alarms only** during your work hours
+4. If running OpenCode as an administrator, PowerShell inherits elevated privileges; some Windows configurations suppress toasts from elevated processes
+
+---
+
+← [Back to Index](index.md)