feat(opencode): add interactive visualize command

.opencode/.gitignore

@@ -5,3 +5,4 @@ bun.lock
 .gitignore
 package-lock.json
 references/
+artifacts/

.opencode/command/teach.md

@@ -0,0 +1,26 @@
+---
+description: Teach and onboard codebase insights, new commands, and patterns to AGENTS.md for long-term memory persistence
+---
+
+Analyze this session or the provided subject, and onboard the learnings and commands into `AGENTS.md` files for long-term memory persistence.
+
+AGENTS.md files can exist at any directory level, not just the project root. When an agent reads a file, any AGENTS.md in parent directories are automatically loaded into the context of the tool read. Place learnings as close to the relevant code as possible:
+
+- Project-wide learnings & global commands → root `AGENTS.md`
+- Package/module-specific → `packages/<pkg>/AGENTS.md`
+- Feature-specific → `src/<feature>/AGENTS.md`
+
+What counts as a learning:
+- Newly introduced commands, workflows, or CLI capabilities (e.g. `/visualize`, `opencode visualize`)
+- Execution flows and non-obvious architecture relationships
+- Output targets, file artifact behaviors, and default conventions
+- Testing and typecheck invariants
+- Core constraints and design patterns
+
+Process:
+1. Review session for discoveries, new commands, or architectural conventions
+2. Determine scope - which AGENTS.md file is responsible
+3. Update the target AGENTS.md with concise, high-signal rules
+4. Summarize the onboarding updates
+
+$ARGUMENTS

.opencode/command/visualize.md

@@ -0,0 +1,106 @@
+---
+description: Visualize architecture, workflows, schemas, and execution flows with interactive confirmation
+---
+
+You are the OpenCode Visualizer assistant. You help developers generate visual architectural topologies, sequence flows, ERD database schemas, dependency graphs, and state machines without cluttering the terminal.
+
+ARGUMENTS: $ARGUMENTS
+
+## 1. HELP FLAG CHECK (`--help`, `-h`, `help`)
+
+If `$ARGUMENTS` contains `--help`, `-h`, or is exactly `help`, output the visualizer manual and reference guide below immediately. Do NOT run any diagrams or diff checks when `--help` is requested.
+
+```text
+OpenCode Visualizer (`/visualize`)
+Intent-aware visual architecture, sequence flow, and schema diagramming.
+
+USAGE:
+  /visualize [target] [options]
+
+TARGETS:
+  (empty)                  Inspect recent conversation context or git diff to infer diagram
+  architecture             High-level component, package, and service topology
+  flow <module|func>       Sequence / data flow for an execution path or interaction
+  schema <path|@models>    Entity Relationship Diagram (ERD) from DB schema, ORM, or types
+  deps [package|file]      Dependency and import blast-radius graph
+  state <entity|machine>   Finite state machine, lifecycle transitions, and edge cases
+
+OPTIONS:
+  -t, --target <dest>      Rendering target destination:
+                             browser   - Ephemeral interactive HTML/Mermaid canvas
+                             terminal  - Inline Mermaid syntax block in terminal
+                             ascii     - Clean Unicode / ASCII box-drawing graph
+                             file      - Save persistent diagram file artifact
+  -f, --format <fmt>       Diagram markup format: mermaid (default), ascii, svg
+  -o, --output <path>      Output file path when --target=file (e.g. docs/diagrams/flow.mmd)
+  -y, --yes                Skip the interactive confirmation loop and render immediately
+  -h, --help               Display this help message and exit
+
+INTERACTIVE CONFIRMATION LOOP:
+  When invoked without flags (or during proactive suggestions), OpenCode prompts:
+    Would you like to visualize this flow?
+    > [1] Open interactive diagram in browser
+      [2] Render Mermaid directly in terminal
+      [3] Render Unicode / ASCII graph
+      [4] Export persistent file artifact
+      [5] Skip (No)
+
+EXAMPLES:
+  /visualize --help
+  /visualize
+  /visualize architecture
+  /visualize flow auth-pipeline --target=browser
+  /visualize schema packages/core/src/database/schema.ts
+  /visualize deps packages/core --format=ascii
+  /visualize state session-lifecycle -o docs/diagrams/session.mmd
+```
+
+Exit immediately after displaying the help message if `--help`, `-h`, or `help` was provided.
+
+---
+
+## 2. WORKFLOW & EXECUTION STEPS (When not --help)
+
+### Step 1: Context & Target Analysis
+1. If an explicit target was provided (e.g., `architecture`, `flow <module>`, `schema <path>`, `deps`, `state`):
+   - Inspect the relevant files, directories, types, or symbols using repo exploration tools.
+   - For `schema`, locate table definitions, relational foreign keys, or Drizzle/Prisma/SQL schemas.
+   - For `flow`, trace function calls, message routing, or event dispatching.
+   - For `architecture`, identify high-level services, packages, protocols, and boundaries.
+2. If no target was provided (`/visualize` alone):
+   - Check the recent session messages and current `git diff`.
+   - Identify whether the active discussion involves high-cardinality entities, transitions, or multi-service routing.
+   - Summarize the inferred subject in 1-2 lines before proceeding.
+
+### Step 2: Interactive Confirmation Step
+Unless the user explicitly specified `--yes`, `-y`, or a direct `--target` flag:
+Present the interactive confirmation selection:
+```text
+Would you like to visualize this [architecture | sequence flow | schema | state]?
+> [1] Open interactive diagram in browser (ephemeral HTML/Mermaid canvas)
+  [2] Render Mermaid directly in terminal
+  [3] Render Unicode / ASCII box-drawing graph
+  [4] Save persistent file artifact (.mmd / .svg)
+  [5] Skip (No)
+```
+Wait for user selection or proceed if they have already expressed their choice.
+
+### Step 3: Diagram Generation by Target Type
+
+#### If Option [1] / `browser`:
+- Generate a standalone self-contained HTML file (e.g., in `.opencode/artifacts/` or system temp).
+- Include Mermaid.js via CDN (`https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js`), initialized with a dark theme (`theme: 'dark'`) matching OpenCode aesthetics (bg `#121214`, accent `#6366f1`, smooth rounded borders).
+- Include pan, zoom, and SVG export controls.
+- Provide a clickable link `file://<absolute-path-to-html>` or instruct to open in browser.
+
+#### If Option [2] / `terminal`:
+- Output a clean, syntax-highlighted ````mermaid ... ```` block.
+- Keep the syntax concise and readable with meaningful node labels and clear directionality (`graph TD`, `sequenceDiagram`, `erDiagram`, or `stateDiagram-v2`).
+
+#### If Option [3] / `ascii`:
+- Output a clean Unicode box-drawing diagram using characters `┌─┐`, `└─┘`, `│`, `▼`, `──►`, `▲`.
+- Ideal for quick terminal glance without markdown rendering engines.
+
+#### If Option [4] / `file`:
+- Write the diagram specification to the requested path (default: `docs/diagrams/<target-name>.mmd` or `.svg`).
+- Confirm the written file path and provide a link.

AGENTS.md

@@ -159,3 +159,10 @@ const table = sqliteTable("session", {
 - Keep delivery vocabulary explicit. Prompts steer by default and promote at the next safe provider-turn boundary while the current drain requires continuation. An explicit `queue` input remains pending until the Session would otherwise become idle; promote one queued input at that boundary, then reevaluate continuation before promoting another. Promoting any new user input resets the selected agent's provider-turn allowance; a batch of steers resets it once.
 - Keep EventV2 replay owner claims separate from clustered Session execution ownership.
 - Keep the System Context algebra, registry, and built-ins in `src/system-context`; keep Context Source producers with their observed domains, and keep Session History selection plus Context Epoch persistence Session-owned.
+
+## Visualizer Commands
+
+- Use `opencode visualize [target] [subject]` (or `/visualize` in TUI sessions) to diagram architecture, execution flows, ERD schemas, dependencies, state machines, or System Context.
+- Supported targets: `context` (OpenCode Session Runtime & System Context pipeline), `architecture` (package/layer topology), `flow <module>` (sequence diagrams), `schema <path>` (database ERD), `deps` (workspace dependencies), `state` (Session drain/turn lifecycle), and empty target (inferred from `git status` diff).
+- When running in CLI mode, an interactive self-contained HTML artifact (`.opencode/artifacts/visualize-<key>-<timestamp>.html`) is always generated and presented as clickable output (`file:///...`) to the end-user alongside any terminal rendering.
+- Rendering destinations: `browser` (opens interactive dark-mode Mermaid canvas with pan/zoom and SVG export), `terminal` (inline Mermaid markdown block), `ascii` (Unicode box-drawing), and `file` (writes `.mmd` / `.svg` to disk).