From 370983eb1ed991def194095f3221370d6924cda1 Mon Sep 17 00:00:00 2001
From: lyx-tec <lyx.tec@gmail.com>
Date: Sat, 30 May 2026 09:19:29 +0800
Subject: [PATCH 1/3] fix: copy-on-select overwrites clipboard when search is
 open (#1) (#2)

* fix: copy-on-select overwrites clipboard when search is open (#1)

Change the guard in termwrap.ts from checking focused element
(document.activeElement.closest) to checking DOM presence
(document.querySelector) to prevent copy-on-select from firing
whenever search is open, regardless of focus state.

* chore: mark verification tasks complete, archive openspec change, sync specs
---
 .github/prompts/opsx-apply.prompt.md          | 149 +++++
 .github/prompts/opsx-archive.prompt.md        | 154 +++++
 .github/prompts/opsx-explore.prompt.md        | 170 ++++++
 .github/prompts/opsx-propose.prompt.md        | 103 ++++
 .github/skills/openspec-apply-change/SKILL.md | 156 +++++
 .../skills/openspec-archive-change/SKILL.md   | 114 ++++
 .github/skills/openspec-explore/SKILL.md      | 288 +++++++++
 .github/skills/openspec-propose/SKILL.md      | 110 ++++
 .gitignore                                    |   2 +
 .../skills/openspec-apply-change/SKILL.md     | 156 +++++
 .../skills/openspec-archive-change/SKILL.md   | 114 ++++
 .kilocode/skills/openspec-explore/SKILL.md    | 288 +++++++++
 .kilocode/skills/openspec-propose/SKILL.md    | 110 ++++
 .kilocode/workflows/opsx-apply.md             | 145 +++++
 .kilocode/workflows/opsx-archive.md           | 150 +++++
 .kilocode/workflows/opsx-explore.md           | 166 +++++
 .kilocode/workflows/opsx-propose.md           |  99 +++
 .roo/commands/opsx-apply.md                   | 149 +++++
 .roo/commands/opsx-archive.md                 | 154 +++++
 .roo/commands/opsx-explore.md                 | 170 ++++++
 .roo/commands/opsx-propose.md                 | 103 ++++
 .roo/skills/openspec-apply-change/SKILL.md    | 156 +++++
 .roo/skills/openspec-archive-change/SKILL.md  | 114 ++++
 .roo/skills/openspec-explore/SKILL.md         | 288 +++++++++
 .roo/skills/openspec-propose/SKILL.md         | 110 ++++
 PROJECT_SUMMARY.md                            | 315 ++++++++++
 frontend/app/view/term/termwrap.ts            |   5 +-
 frontend/types/gotypes.d.ts                   |   1 +
 go.mod                                        |   1 +
 go.sum                                        |   2 +
 .../.openspec.yaml                            |   2 +
 .../design.md                                 |  47 ++
 .../proposal.md                               |  23 +
 .../specs/search-clipboard-guard/spec.md      |  15 +
 .../tasks.md                                  |  10 +
 openspec/specs/search-clipboard-guard/spec.md |  15 +
 package-lock.json                             | 573 +-----------------
 package.json                                  |   2 +-
 38 files changed, 4154 insertions(+), 575 deletions(-)
 create mode 100644 .github/prompts/opsx-apply.prompt.md
 create mode 100644 .github/prompts/opsx-archive.prompt.md
 create mode 100644 .github/prompts/opsx-explore.prompt.md
 create mode 100644 .github/prompts/opsx-propose.prompt.md
 create mode 100644 .github/skills/openspec-apply-change/SKILL.md
 create mode 100644 .github/skills/openspec-archive-change/SKILL.md
 create mode 100644 .github/skills/openspec-explore/SKILL.md
 create mode 100644 .github/skills/openspec-propose/SKILL.md
 create mode 100644 .kilocode/skills/openspec-apply-change/SKILL.md
 create mode 100644 .kilocode/skills/openspec-archive-change/SKILL.md
 create mode 100644 .kilocode/skills/openspec-explore/SKILL.md
 create mode 100644 .kilocode/skills/openspec-propose/SKILL.md
 create mode 100644 .kilocode/workflows/opsx-apply.md
 create mode 100644 .kilocode/workflows/opsx-archive.md
 create mode 100644 .kilocode/workflows/opsx-explore.md
 create mode 100644 .kilocode/workflows/opsx-propose.md
 create mode 100644 .roo/commands/opsx-apply.md
 create mode 100644 .roo/commands/opsx-archive.md
 create mode 100644 .roo/commands/opsx-explore.md
 create mode 100644 .roo/commands/opsx-propose.md
 create mode 100644 .roo/skills/openspec-apply-change/SKILL.md
 create mode 100644 .roo/skills/openspec-archive-change/SKILL.md
 create mode 100644 .roo/skills/openspec-explore/SKILL.md
 create mode 100644 .roo/skills/openspec-propose/SKILL.md
 create mode 100644 PROJECT_SUMMARY.md
 create mode 100644 openspec/changes/archive/2026-05-30-fix-search-copyonselect-clipboard/.openspec.yaml
 create mode 100644 openspec/changes/archive/2026-05-30-fix-search-copyonselect-clipboard/design.md
 create mode 100644 openspec/changes/archive/2026-05-30-fix-search-copyonselect-clipboard/proposal.md
 create mode 100644 openspec/changes/archive/2026-05-30-fix-search-copyonselect-clipboard/specs/search-clipboard-guard/spec.md
 create mode 100644 openspec/changes/archive/2026-05-30-fix-search-copyonselect-clipboard/tasks.md
 create mode 100644 openspec/specs/search-clipboard-guard/spec.md

diff --git a/.github/prompts/opsx-apply.prompt.md b/.github/prompts/opsx-apply.prompt.md
new file mode 100644
index 0000000000..e23ec64d14
--- /dev/null
+++ b/.github/prompts/opsx-apply.prompt.md
@@ -0,0 +1,149 @@
+---
+description: Implement tasks from an OpenSpec change (Experimental)
+---
+
+Implement tasks from an OpenSpec change.
+
+**Input**: Optionally specify a change name (e.g., `/opsx:apply add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **Select the change**
+
+   If a name is provided, use it. Otherwise:
+   - Infer from conversation context if the user mentioned a change
+   - Auto-select if only one active change exists
+   - If ambiguous, run `openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select
+
+   Always announce: "Using change: <name>" and how to override (e.g., `/opsx:apply <other>`).
+
+2. **Check status to understand the schema**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used (e.g., "spec-driven")
+   - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
+
+3. **Get apply instructions**
+
+   ```bash
+   openspec instructions apply --change "<name>" --json
+   ```
+
+   This returns:
+   - `contextFiles`: artifact ID -> array of concrete file paths (varies by schema)
+   - Progress (total, complete, remaining)
+   - Task list with status
+   - Dynamic instruction based on current state
+
+   **Handle states:**
+   - If `state: "blocked"` (missing artifacts): show message, suggest using `/opsx:continue`
+   - If `state: "all_done"`: congratulate, suggest archive
+   - Otherwise: proceed to implementation
+
+4. **Read context files**
+
+   Read every file path listed under `contextFiles` from the apply instructions output.
+   The files depend on the schema being used:
+   - **spec-driven**: proposal, specs, design, tasks
+   - Other schemas: follow the contextFiles from CLI output
+
+5. **Show current progress**
+
+   Display:
+   - Schema being used
+   - Progress: "N/M tasks complete"
+   - Remaining tasks overview
+   - Dynamic instruction from CLI
+
+6. **Implement tasks (loop until done or blocked)**
+
+   For each pending task:
+   - Show which task is being worked on
+   - Make the code changes required
+   - Keep changes minimal and focused
+   - Mark task complete in the tasks file: `- [ ]` → `- [x]`
+   - Continue to next task
+
+   **Pause if:**
+   - Task is unclear → ask for clarification
+   - Implementation reveals a design issue → suggest updating artifacts
+   - Error or blocker encountered → report and wait for guidance
+   - User interrupts
+
+7. **On completion or pause, show status**
+
+   Display:
+   - Tasks completed this session
+   - Overall progress: "N/M tasks complete"
+   - If all done: suggest archive
+   - If paused: explain why and wait for guidance
+
+**Output During Implementation**
+
+```
+## Implementing: <change-name> (schema: <schema-name>)
+
+Working on task 3/7: <task description>
+[...implementation happening...]
+✓ Task complete
+
+Working on task 4/7: <task description>
+[...implementation happening...]
+✓ Task complete
+```
+
+**Output On Completion**
+
+```
+## Implementation Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Progress:** 7/7 tasks complete ✓
+
+### Completed This Session
+- [x] Task 1
+- [x] Task 2
+...
+
+All tasks complete! You can archive this change with `/opsx:archive`.
+```
+
+**Output On Pause (Issue Encountered)**
+
+```
+## Implementation Paused
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Progress:** 4/7 tasks complete
+
+### Issue Encountered
+<description of the issue>
+
+**Options:**
+1. <option 1>
+2. <option 2>
+3. Other approach
+
+What would you like to do?
+```
+
+**Guardrails**
+- Keep going through tasks until done or blocked
+- Always read context files before starting (from the apply instructions output)
+- If task is ambiguous, pause and ask before implementing
+- If implementation reveals issues, pause and suggest artifact updates
+- Keep code changes minimal and scoped to each task
+- Update task checkbox immediately after completing each task
+- Pause on errors, blockers, or unclear requirements - don't guess
+- Use contextFiles from CLI output, don't assume specific file names
+
+**Fluid Workflow Integration**
+
+This skill supports the "actions on a change" model:
+
+- **Can be invoked anytime**: Before all artifacts are done (if tasks exist), after partial implementation, interleaved with other actions
+- **Allows artifact updates**: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly
diff --git a/.github/prompts/opsx-archive.prompt.md b/.github/prompts/opsx-archive.prompt.md
new file mode 100644
index 0000000000..1163776da4
--- /dev/null
+++ b/.github/prompts/opsx-archive.prompt.md
@@ -0,0 +1,154 @@
+---
+description: Archive a completed change in the experimental workflow
+---
+
+Archive a completed change in the experimental workflow.
+
+**Input**: Optionally specify a change name after `/opsx:archive` (e.g., `/opsx:archive add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+
+   Show only active changes (not already archived).
+   Include the schema used for each change if available.
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Check artifact completion status**
+
+   Run `openspec status --change "<name>" --json` to check artifact completion.
+
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used
+   - `artifacts`: List of artifacts with their status (`done` or other)
+
+   **If any artifacts are not `done`:**
+   - Display warning listing incomplete artifacts
+   - Prompt user for confirmation to continue
+   - Proceed if user confirms
+
+3. **Check task completion status**
+
+   Read the tasks file (typically `tasks.md`) to check for incomplete tasks.
+
+   Count tasks marked with `- [ ]` (incomplete) vs `- [x]` (complete).
+
+   **If incomplete tasks found:**
+   - Display warning showing count of incomplete tasks
+   - Prompt user for confirmation to continue
+   - Proceed if user confirms
+
+   **If no tasks file exists:** Proceed without task-related warning.
+
+4. **Assess delta spec sync state**
+
+   Check for delta specs at `openspec/changes/<name>/specs/`. If none exist, proceed without sync prompt.
+
+   **If delta specs exist:**
+   - Compare each delta spec with its corresponding main spec at `openspec/specs/<capability>/spec.md`
+   - Determine what changes would be applied (adds, modifications, removals, renames)
+   - Show a combined summary before prompting
+
+   **Prompt options:**
+   - If changes needed: "Sync now (recommended)", "Archive without syncing"
+   - If already synced: "Archive now", "Sync anyway", "Cancel"
+
+   If user chooses sync, use Task tool (subagent_type: "general-purpose", prompt: "Use Skill tool to invoke openspec-sync-specs for change '<name>'. Delta spec analysis: <include the analyzed delta spec summary>"). Proceed to archive regardless of choice.
+
+5. **Perform the archive**
+
+   Create the archive directory if it doesn't exist:
+   ```bash
+   mkdir -p openspec/changes/archive
+   ```
+
+   Generate target name using current date: `YYYY-MM-DD-<change-name>`
+
+   **Check if target already exists:**
+   - If yes: Fail with error, suggest renaming existing archive or using different date
+   - If no: Move the change directory to archive
+
+   ```bash
+   mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
+   ```
+
+6. **Display summary**
+
+   Show archive completion summary including:
+   - Change name
+   - Schema that was used
+   - Archive location
+   - Spec sync status (synced / sync skipped / no delta specs)
+   - Note about any warnings (incomplete artifacts/tasks)
+
+**Output On Success**
+
+```
+## Archive Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** ✓ Synced to main specs
+
+All artifacts complete. All tasks complete.
+```
+
+**Output On Success (No Delta Specs)**
+
+```
+## Archive Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** No delta specs
+
+All artifacts complete. All tasks complete.
+```
+
+**Output On Success With Warnings**
+
+```
+## Archive Complete (with warnings)
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** Sync skipped (user chose to skip)
+
+**Warnings:**
+- Archived with 2 incomplete artifacts
+- Archived with 3 incomplete tasks
+- Delta spec sync was skipped (user chose to skip)
+
+Review the archive if this was not intentional.
+```
+
+**Output On Error (Archive Exists)**
+
+```
+## Archive Failed
+
+**Change:** <change-name>
+**Target:** openspec/changes/archive/YYYY-MM-DD-<name>/
+
+Target archive directory already exists.
+
+**Options:**
+1. Rename the existing archive
+2. Delete the existing archive if it's a duplicate
+3. Wait until a different date to archive
+```
+
+**Guardrails**
+- Always prompt for change selection if not provided
+- Use artifact graph (openspec status --json) for completion checking
+- Don't block archive on warnings - just inform and confirm
+- Preserve .openspec.yaml when moving to archive (it moves with the directory)
+- Show clear summary of what happened
+- If sync is requested, use the Skill tool to invoke `openspec-sync-specs` (agent-driven)
+- If delta specs exist, always run the sync assessment and show the combined summary before prompting
diff --git a/.github/prompts/opsx-explore.prompt.md b/.github/prompts/opsx-explore.prompt.md
new file mode 100644
index 0000000000..3b674ebb57
--- /dev/null
+++ b/.github/prompts/opsx-explore.prompt.md
@@ -0,0 +1,170 @@
+---
+description: Enter explore mode - think through ideas, investigate problems, clarify requirements
+---
+
+Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
+
+**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing.
+
+**This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.
+
+**Input**: The argument after `/opsx:explore` is whatever the user wants to think about. Could be:
+- A vague idea: "real-time collaboration"
+- A specific problem: "the auth system is getting unwieldy"
+- A change name: "add-dark-mode" (to explore in context of that change)
+- A comparison: "postgres vs sqlite for this"
+- Nothing (just enter explore mode)
+
+---
+
+## The Stance
+
+- **Curious, not prescriptive** - Ask questions that emerge naturally, don't follow a script
+- **Open threads, not interrogations** - Surface multiple interesting directions and let the user follow what resonates. Don't funnel them through a single path of questions.
+- **Visual** - Use ASCII diagrams liberally when they'd help clarify thinking
+- **Adaptive** - Follow interesting threads, pivot when new information emerges
+- **Patient** - Don't rush to conclusions, let the shape of the problem emerge
+- **Grounded** - Explore the actual codebase when relevant, don't just theorize
+
+---
+
+## What You Might Do
+
+Depending on what the user brings, you might:
+
+**Explore the problem space**
+- Ask clarifying questions that emerge from what they said
+- Challenge assumptions
+- Reframe the problem
+- Find analogies
+
+**Investigate the codebase**
+- Map existing architecture relevant to the discussion
+- Find integration points
+- Identify patterns already in use
+- Surface hidden complexity
+
+**Compare options**
+- Brainstorm multiple approaches
+- Build comparison tables
+- Sketch tradeoffs
+- Recommend a path (if asked)
+
+**Visualize**
+```
+┌─────────────────────────────────────────┐
+│     Use ASCII diagrams liberally        │
+├─────────────────────────────────────────┤
+│                                         │
+│      ┌────────┐         ┌────────┐      │
+│      │ State  │────────▶│ State  │      │
+│      │   A    │         │   B    │      │
+│      └────────┘         └────────┘      │
+│                                         │
+│   System diagrams, state machines,      │
+│   data flows, architecture sketches,    │
+│   dependency graphs, comparison tables  │
+│                                         │
+└─────────────────────────────────────────┘
+```
+
+**Surface risks and unknowns**
+- Identify what could go wrong
+- Find gaps in understanding
+- Suggest spikes or investigations
+
+---
+
+## OpenSpec Awareness
+
+You have full context of the OpenSpec system. Use it naturally, don't force it.
+
+### Check for context
+
+At the start, quickly check what exists:
+```bash
+openspec list --json
+```
+
+This tells you:
+- If there are active changes
+- Their names, schemas, and status
+- What the user might be working on
+
+If the user mentioned a specific change name, read its artifacts for context.
+
+### When no change exists
+
+Think freely. When insights crystallize, you might offer:
+
+- "This feels solid enough to start a change. Want me to create a proposal?"
+- Or keep exploring - no pressure to formalize
+
+### When a change exists
+
+If the user mentions a change or you detect one is relevant:
+
+1. **Read existing artifacts for context**
+   - `openspec/changes/<name>/proposal.md`
+   - `openspec/changes/<name>/design.md`
+   - `openspec/changes/<name>/tasks.md`
+   - etc.
+
+2. **Reference them naturally in conversation**
+   - "Your design mentions using Redis, but we just realized SQLite fits better..."
+   - "The proposal scopes this to premium users, but we're now thinking everyone..."
+
+3. **Offer to capture when decisions are made**
+
+    | Insight Type               | Where to Capture               |
+    |----------------------------|--------------------------------|
+    | New requirement discovered | `specs/<capability>/spec.md` |
+    | Requirement changed        | `specs/<capability>/spec.md` |
+    | Design decision made       | `design.md`                  |
+    | Scope changed              | `proposal.md`                |
+    | New work identified        | `tasks.md`                   |
+    | Assumption invalidated     | Relevant artifact              |
+
+   Example offers:
+   - "That's a design decision. Capture it in design.md?"
+   - "This is a new requirement. Add it to specs?"
+   - "This changes scope. Update the proposal?"
+
+4. **The user decides** - Offer and move on. Don't pressure. Don't auto-capture.
+
+---
+
+## What You Don't Have To Do
+
+- Follow a script
+- Ask the same questions every time
+- Produce a specific artifact
+- Reach a conclusion
+- Stay on topic if a tangent is valuable
+- Be brief (this is thinking time)
+
+---
+
+## Ending Discovery
+
+There's no required ending. Discovery might:
+
+- **Flow into a proposal**: "Ready to start? I can create a change proposal."
+- **Result in artifact updates**: "Updated design.md with these decisions"
+- **Just provide clarity**: User has what they need, moves on
+- **Continue later**: "We can pick this up anytime"
+
+When things crystallize, you might offer a summary - but it's optional. Sometimes the thinking IS the value.
+
+---
+
+## Guardrails
+
+- **Don't implement** - Never write code or implement features. Creating OpenSpec artifacts is fine, writing application code is not.
+- **Don't fake understanding** - If something is unclear, dig deeper
+- **Don't rush** - Discovery is thinking time, not task time
+- **Don't force structure** - Let patterns emerge naturally
+- **Don't auto-capture** - Offer to save insights, don't just do it
+- **Do visualize** - A good diagram is worth many paragraphs
+- **Do explore the codebase** - Ground discussions in reality
+- **Do question assumptions** - Including the user's and your own
diff --git a/.github/prompts/opsx-propose.prompt.md b/.github/prompts/opsx-propose.prompt.md
new file mode 100644
index 0000000000..cf30b2a550
--- /dev/null
+++ b/.github/prompts/opsx-propose.prompt.md
@@ -0,0 +1,103 @@
+---
+description: Propose a new change - create it and generate all artifacts in one step
+---
+
+Propose a new change - create the change and generate all artifacts in one step.
+
+I'll create a change with artifacts:
+- proposal.md (what & why)
+- design.md (how)
+- tasks.md (implementation steps)
+
+When ready to implement, run /opsx:apply
+
+---
+
+**Input**: The argument after `/opsx:propose` is the change name (kebab-case), OR a description of what the user wants to build.
+
+**Steps**
+
+1. **If no input provided, ask what they want to build**
+
+   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+   > "What change do you want to work on? Describe what you want to build or fix."
+
+   From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
+
+   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
+
+2. **Create the change directory**
+   ```bash
+   openspec new change "<name>"
+   ```
+   This creates a scaffolded change at `openspec/changes/<name>/` with `.openspec.yaml`.
+
+3. **Get the artifact build order**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to get:
+   - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
+   - `artifacts`: list of all artifacts with their status and dependencies
+
+4. **Create artifacts in sequence until apply-ready**
+
+   Use the **TodoWrite tool** to track progress through the artifacts.
+
+   Loop through artifacts in dependency order (artifacts with no pending dependencies first):
+
+   a. **For each artifact that is `ready` (dependencies satisfied)**:
+      - Get instructions:
+        ```bash
+        openspec instructions <artifact-id> --change "<name>" --json
+        ```
+      - The instructions JSON includes:
+        - `context`: Project background (constraints for you - do NOT include in output)
+        - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
+        - `template`: The structure to use for your output file
+        - `instruction`: Schema-specific guidance for this artifact type
+        - `outputPath`: Where to write the artifact
+        - `dependencies`: Completed artifacts to read for context
+      - Read any completed dependency files for context
+      - Create the artifact file using `template` as the structure
+      - Apply `context` and `rules` as constraints - but do NOT copy them into the file
+      - Show brief progress: "Created <artifact-id>"
+
+   b. **Continue until all `applyRequires` artifacts are complete**
+      - After creating each artifact, re-run `openspec status --change "<name>" --json`
+      - Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array
+      - Stop when all `applyRequires` artifacts are done
+
+   c. **If an artifact requires user input** (unclear context):
+      - Use **AskUserQuestion tool** to clarify
+      - Then continue with creation
+
+5. **Show final status**
+   ```bash
+   openspec status --change "<name>"
+   ```
+
+**Output**
+
+After completing all artifacts, summarize:
+- Change name and location
+- List of artifacts created with brief descriptions
+- What's ready: "All artifacts created! Ready for implementation."
+- Prompt: "Run `/opsx:apply` to start implementing."
+
+**Artifact Creation Guidelines**
+
+- Follow the `instruction` field from `openspec instructions` for each artifact type
+- The schema defines what each artifact should contain - follow it
+- Read dependency artifacts for context before creating new ones
+- Use `template` as the structure for your output file - fill in its sections
+- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
+  - Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
+  - These guide what you write, but should never appear in the output
+
+**Guardrails**
+- Create ALL artifacts needed for implementation (as defined by schema's `apply.requires`)
+- Always read dependency artifacts before creating a new one
+- If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
+- If a change with that name already exists, ask if user wants to continue it or create a new one
+- Verify each artifact file exists after writing before proceeding to next
diff --git a/.github/skills/openspec-apply-change/SKILL.md b/.github/skills/openspec-apply-change/SKILL.md
new file mode 100644
index 0000000000..70fbdb8569
--- /dev/null
+++ b/.github/skills/openspec-apply-change/SKILL.md
@@ -0,0 +1,156 @@
+---
+name: openspec-apply-change
+description: Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.3.1"
+---
+
+Implement tasks from an OpenSpec change.
+
+**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **Select the change**
+
+   If a name is provided, use it. Otherwise:
+   - Infer from conversation context if the user mentioned a change
+   - Auto-select if only one active change exists
+   - If ambiguous, run `openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select
+
+   Always announce: "Using change: <name>" and how to override (e.g., `/opsx:apply <other>`).
+
+2. **Check status to understand the schema**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used (e.g., "spec-driven")
+   - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
+
+3. **Get apply instructions**
+
+   ```bash
+   openspec instructions apply --change "<name>" --json
+   ```
+
+   This returns:
+   - `contextFiles`: artifact ID -> array of concrete file paths (varies by schema - could be proposal/specs/design/tasks or spec/tests/implementation/docs)
+   - Progress (total, complete, remaining)
+   - Task list with status
+   - Dynamic instruction based on current state
+
+   **Handle states:**
+   - If `state: "blocked"` (missing artifacts): show message, suggest using openspec-continue-change
+   - If `state: "all_done"`: congratulate, suggest archive
+   - Otherwise: proceed to implementation
+
+4. **Read context files**
+
+   Read every file path listed under `contextFiles` from the apply instructions output.
+   The files depend on the schema being used:
+   - **spec-driven**: proposal, specs, design, tasks
+   - Other schemas: follow the contextFiles from CLI output
+
+5. **Show current progress**
+
+   Display:
+   - Schema being used
+   - Progress: "N/M tasks complete"
+   - Remaining tasks overview
+   - Dynamic instruction from CLI
+
+6. **Implement tasks (loop until done or blocked)**
+
+   For each pending task:
+   - Show which task is being worked on
+   - Make the code changes required
+   - Keep changes minimal and focused
+   - Mark task complete in the tasks file: `- [ ]` → `- [x]`
+   - Continue to next task
+
+   **Pause if:**
+   - Task is unclear → ask for clarification
+   - Implementation reveals a design issue → suggest updating artifacts
+   - Error or blocker encountered → report and wait for guidance
+   - User interrupts
+
+7. **On completion or pause, show status**
+
+   Display:
+   - Tasks completed this session
+   - Overall progress: "N/M tasks complete"
+   - If all done: suggest archive
+   - If paused: explain why and wait for guidance
+
+**Output During Implementation**
+
+```
+## Implementing: <change-name> (schema: <schema-name>)
+
+Working on task 3/7: <task description>
+[...implementation happening...]
+✓ Task complete
+
+Working on task 4/7: <task description>
+[...implementation happening...]
+✓ Task complete
+```
+
+**Output On Completion**
+
+```
+## Implementation Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Progress:** 7/7 tasks complete ✓
+
+### Completed This Session
+- [x] Task 1
+- [x] Task 2
+...
+
+All tasks complete! Ready to archive this change.
+```
+
+**Output On Pause (Issue Encountered)**
+
+```
+## Implementation Paused
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Progress:** 4/7 tasks complete
+
+### Issue Encountered
+<description of the issue>
+
+**Options:**
+1. <option 1>
+2. <option 2>
+3. Other approach
+
+What would you like to do?
+```
+
+**Guardrails**
+- Keep going through tasks until done or blocked
+- Always read context files before starting (from the apply instructions output)
+- If task is ambiguous, pause and ask before implementing
+- If implementation reveals issues, pause and suggest artifact updates
+- Keep code changes minimal and scoped to each task
+- Update task checkbox immediately after completing each task
+- Pause on errors, blockers, or unclear requirements - don't guess
+- Use contextFiles from CLI output, don't assume specific file names
+
+**Fluid Workflow Integration**
+
+This skill supports the "actions on a change" model:
+
+- **Can be invoked anytime**: Before all artifacts are done (if tasks exist), after partial implementation, interleaved with other actions
+- **Allows artifact updates**: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly
diff --git a/.github/skills/openspec-archive-change/SKILL.md b/.github/skills/openspec-archive-change/SKILL.md
new file mode 100644
index 0000000000..12e2f70e9c
--- /dev/null
+++ b/.github/skills/openspec-archive-change/SKILL.md
@@ -0,0 +1,114 @@
+---
+name: openspec-archive-change
+description: Archive a completed change in the experimental workflow. Use when the user wants to finalize and archive a change after implementation is complete.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.3.1"
+---
+
+Archive a completed change in the experimental workflow.
+
+**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+
+   Show only active changes (not already archived).
+   Include the schema used for each change if available.
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Check artifact completion status**
+
+   Run `openspec status --change "<name>" --json` to check artifact completion.
+
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used
+   - `artifacts`: List of artifacts with their status (`done` or other)
+
+   **If any artifacts are not `done`:**
+   - Display warning listing incomplete artifacts
+   - Use **AskUserQuestion tool** to confirm user wants to proceed
+   - Proceed if user confirms
+
+3. **Check task completion status**
+
+   Read the tasks file (typically `tasks.md`) to check for incomplete tasks.
+
+   Count tasks marked with `- [ ]` (incomplete) vs `- [x]` (complete).
+
+   **If incomplete tasks found:**
+   - Display warning showing count of incomplete tasks
+   - Use **AskUserQuestion tool** to confirm user wants to proceed
+   - Proceed if user confirms
+
+   **If no tasks file exists:** Proceed without task-related warning.
+
+4. **Assess delta spec sync state**
+
+   Check for delta specs at `openspec/changes/<name>/specs/`. If none exist, proceed without sync prompt.
+
+   **If delta specs exist:**
+   - Compare each delta spec with its corresponding main spec at `openspec/specs/<capability>/spec.md`
+   - Determine what changes would be applied (adds, modifications, removals, renames)
+   - Show a combined summary before prompting
+
+   **Prompt options:**
+   - If changes needed: "Sync now (recommended)", "Archive without syncing"
+   - If already synced: "Archive now", "Sync anyway", "Cancel"
+
+   If user chooses sync, use Task tool (subagent_type: "general-purpose", prompt: "Use Skill tool to invoke openspec-sync-specs for change '<name>'. Delta spec analysis: <include the analyzed delta spec summary>"). Proceed to archive regardless of choice.
+
+5. **Perform the archive**
+
+   Create the archive directory if it doesn't exist:
+   ```bash
+   mkdir -p openspec/changes/archive
+   ```
+
+   Generate target name using current date: `YYYY-MM-DD-<change-name>`
+
+   **Check if target already exists:**
+   - If yes: Fail with error, suggest renaming existing archive or using different date
+   - If no: Move the change directory to archive
+
+   ```bash
+   mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
+   ```
+
+6. **Display summary**
+
+   Show archive completion summary including:
+   - Change name
+   - Schema that was used
+   - Archive location
+   - Whether specs were synced (if applicable)
+   - Note about any warnings (incomplete artifacts/tasks)
+
+**Output On Success**
+
+```
+## Archive Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** ✓ Synced to main specs (or "No delta specs" or "Sync skipped")
+
+All artifacts complete. All tasks complete.
+```
+
+**Guardrails**
+- Always prompt for change selection if not provided
+- Use artifact graph (openspec status --json) for completion checking
+- Don't block archive on warnings - just inform and confirm
+- Preserve .openspec.yaml when moving to archive (it moves with the directory)
+- Show clear summary of what happened
+- If sync is requested, use openspec-sync-specs approach (agent-driven)
+- If delta specs exist, always run the sync assessment and show the combined summary before prompting
diff --git a/.github/skills/openspec-explore/SKILL.md b/.github/skills/openspec-explore/SKILL.md
new file mode 100644
index 0000000000..6858d3f693
--- /dev/null
+++ b/.github/skills/openspec-explore/SKILL.md
@@ -0,0 +1,288 @@
+---
+name: openspec-explore
+description: Enter explore mode - a thinking partner for exploring ideas, investigating problems, and clarifying requirements. Use when the user wants to think through something before or during a change.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.3.1"
+---
+
+Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
+
+**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing.
+
+**This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.
+
+---
+
+## The Stance
+
+- **Curious, not prescriptive** - Ask questions that emerge naturally, don't follow a script
+- **Open threads, not interrogations** - Surface multiple interesting directions and let the user follow what resonates. Don't funnel them through a single path of questions.
+- **Visual** - Use ASCII diagrams liberally when they'd help clarify thinking
+- **Adaptive** - Follow interesting threads, pivot when new information emerges
+- **Patient** - Don't rush to conclusions, let the shape of the problem emerge
+- **Grounded** - Explore the actual codebase when relevant, don't just theorize
+
+---
+
+## What You Might Do
+
+Depending on what the user brings, you might:
+
+**Explore the problem space**
+- Ask clarifying questions that emerge from what they said
+- Challenge assumptions
+- Reframe the problem
+- Find analogies
+
+**Investigate the codebase**
+- Map existing architecture relevant to the discussion
+- Find integration points
+- Identify patterns already in use
+- Surface hidden complexity
+
+**Compare options**
+- Brainstorm multiple approaches
+- Build comparison tables
+- Sketch tradeoffs
+- Recommend a path (if asked)
+
+**Visualize**
+```
+┌─────────────────────────────────────────┐
+│     Use ASCII diagrams liberally        │
+├─────────────────────────────────────────┤
+│                                         │
+│      ┌────────┐         ┌────────┐      │
+│      │ State  │────────▶│ State  │      │
+│      │   A    │         │   B    │      │
+│      └────────┘         └────────┘      │
+│                                         │
+│   System diagrams, state machines,      │
+│   data flows, architecture sketches,    │
+│   dependency graphs, comparison tables  │
+│                                         │
+└─────────────────────────────────────────┘
+```
+
+**Surface risks and unknowns**
+- Identify what could go wrong
+- Find gaps in understanding
+- Suggest spikes or investigations
+
+---
+
+## OpenSpec Awareness
+
+You have full context of the OpenSpec system. Use it naturally, don't force it.
+
+### Check for context
+
+At the start, quickly check what exists:
+```bash
+openspec list --json
+```
+
+This tells you:
+- If there are active changes
+- Their names, schemas, and status
+- What the user might be working on
+
+### When no change exists
+
+Think freely. When insights crystallize, you might offer:
+
+- "This feels solid enough to start a change. Want me to create a proposal?"
+- Or keep exploring - no pressure to formalize
+
+### When a change exists
+
+If the user mentions a change or you detect one is relevant:
+
+1. **Read existing artifacts for context**
+   - `openspec/changes/<name>/proposal.md`
+   - `openspec/changes/<name>/design.md`
+   - `openspec/changes/<name>/tasks.md`
+   - etc.
+
+2. **Reference them naturally in conversation**
+   - "Your design mentions using Redis, but we just realized SQLite fits better..."
+   - "The proposal scopes this to premium users, but we're now thinking everyone..."
+
+3. **Offer to capture when decisions are made**
+
+    | Insight Type               | Where to Capture               |
+    |----------------------------|--------------------------------|
+    | New requirement discovered | `specs/<capability>/spec.md` |
+    | Requirement changed        | `specs/<capability>/spec.md` |
+    | Design decision made       | `design.md`                  |
+    | Scope changed              | `proposal.md`                |
+    | New work identified        | `tasks.md`                   |
+    | Assumption invalidated     | Relevant artifact              |
+
+   Example offers:
+   - "That's a design decision. Capture it in design.md?"
+   - "This is a new requirement. Add it to specs?"
+   - "This changes scope. Update the proposal?"
+
+4. **The user decides** - Offer and move on. Don't pressure. Don't auto-capture.
+
+---
+
+## What You Don't Have To Do
+
+- Follow a script
+- Ask the same questions every time
+- Produce a specific artifact
+- Reach a conclusion
+- Stay on topic if a tangent is valuable
+- Be brief (this is thinking time)
+
+---
+
+## Handling Different Entry Points
+
+**User brings a vague idea:**
+```
+User: I'm thinking about adding real-time collaboration
+
+You: Real-time collab is a big space. Let me think about this...
+
+      COLLABORATION SPECTRUM
+      ════════════════════════════════════════════
+
+      Awareness          Coordination         Sync
+          │                   │                 │
+          ▼                   ▼                 ▼
+      ┌────────┐         ┌────────┐        ┌────────┐
+      │Presence│         │Cursors │        │  CRDT  │
+      │  "3    │         │ Multi  │        │Conflict│
+      │online" │         │ select │        │  free  │
+      └────────┘         └────────┘        └────────┘
+          │                   │                 │
+       trivial            moderate           complex
+
+      Where's your head at?
+```
+
+**User brings a specific problem:**
+```
+User: The auth system is a mess
+
+You: [reads codebase]
+
+     ┌─────────────────────────────────────────────┐
+     │              CURRENT AUTH FLOW              │
+     └─────────────────────────────────────────────┘
+                        │
+          ┌─────────────┼─────────────┐
+          ▼             ▼             ▼
+     ┌─────────┐  ┌─────────┐  ┌─────────┐
+     │ Google  │  │  GitHub │  │  Email  │
+     │  OAuth  │  │  OAuth  │  │  Magic  │
+     └────┬────┘  └────┬────┘  └────┬────┘
+          │             │             │
+          └─────────────┼─────────────┘
+                        ▼
+                  ┌───────────┐
+                  │  Session  │
+                  └─────┬─────┘
+                        │
+                        ▼
+                  ┌───────────┐
+                  │   Perms   │
+                  └───────────┘
+
+     I see three tangles. Which one's burning?
+```
+
+**User is stuck mid-implementation:**
+```
+User: /opsx:explore add-auth-system
+      The OAuth integration is more complex than expected
+
+You: [reads change artifacts]
+
+     You're on task 4: "Implement OAuth flow"
+
+     Let me trace what's involved...
+
+     [draws diagram, explores options, suggests paths]
+
+     Want to update the design to reflect this?
+     Or add a spike task to investigate?
+```
+
+**User wants to compare options:**
+```
+User: Should we use Postgres or SQLite?
+
+You: Generic answer is boring. What's the context?
+
+User: A CLI tool that tracks local dev environments
+
+You: That changes everything.
+
+     ┌─────────────────────────────────────────────────┐
+     │          CLI TOOL DATA STORAGE                  │
+     └─────────────────────────────────────────────────┘
+
+     Key constraints:
+     • No daemon running
+     • Must work offline
+     • Single user
+
+                  SQLite          Postgres
+     Deployment   embedded ✓      needs server ✗
+     Offline      yes ✓           no ✗
+     Single file  yes ✓           no ✗
+
+     SQLite. Not even close.
+
+     Unless... is there a sync component?
+```
+
+---
+
+## Ending Discovery
+
+There's no required ending. Discovery might:
+
+- **Flow into a proposal**: "Ready to start? I can create a change proposal."
+- **Result in artifact updates**: "Updated design.md with these decisions"
+- **Just provide clarity**: User has what they need, moves on
+- **Continue later**: "We can pick this up anytime"
+
+When it feels like things are crystallizing, you might summarize:
+
+```
+## What We Figured Out
+
+**The problem**: [crystallized understanding]
+
+**The approach**: [if one emerged]
+
+**Open questions**: [if any remain]
+
+**Next steps** (if ready):
+- Create a change proposal
+- Keep exploring: just keep talking
+```
+
+But this summary is optional. Sometimes the thinking IS the value.
+
+---
+
+## Guardrails
+
+- **Don't implement** - Never write code or implement features. Creating OpenSpec artifacts is fine, writing application code is not.
+- **Don't fake understanding** - If something is unclear, dig deeper
+- **Don't rush** - Discovery is thinking time, not task time
+- **Don't force structure** - Let patterns emerge naturally
+- **Don't auto-capture** - Offer to save insights, don't just do it
+- **Do visualize** - A good diagram is worth many paragraphs
+- **Do explore the codebase** - Ground discussions in reality
+- **Do question assumptions** - Including the user's and your own
diff --git a/.github/skills/openspec-propose/SKILL.md b/.github/skills/openspec-propose/SKILL.md
new file mode 100644
index 0000000000..4b7e204184
--- /dev/null
+++ b/.github/skills/openspec-propose/SKILL.md
@@ -0,0 +1,110 @@
+---
+name: openspec-propose
+description: Propose a new change with all artifacts generated in one step. Use when the user wants to quickly describe what they want to build and get a complete proposal with design, specs, and tasks ready for implementation.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.3.1"
+---
+
+Propose a new change - create the change and generate all artifacts in one step.
+
+I'll create a change with artifacts:
+- proposal.md (what & why)
+- design.md (how)
+- tasks.md (implementation steps)
+
+When ready to implement, run /opsx:apply
+
+---
+
+**Input**: The user's request should include a change name (kebab-case) OR a description of what they want to build.
+
+**Steps**
+
+1. **If no clear input provided, ask what they want to build**
+
+   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+   > "What change do you want to work on? Describe what you want to build or fix."
+
+   From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
+
+   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
+
+2. **Create the change directory**
+   ```bash
+   openspec new change "<name>"
+   ```
+   This creates a scaffolded change at `openspec/changes/<name>/` with `.openspec.yaml`.
+
+3. **Get the artifact build order**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to get:
+   - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
+   - `artifacts`: list of all artifacts with their status and dependencies
+
+4. **Create artifacts in sequence until apply-ready**
+
+   Use the **TodoWrite tool** to track progress through the artifacts.
+
+   Loop through artifacts in dependency order (artifacts with no pending dependencies first):
+
+   a. **For each artifact that is `ready` (dependencies satisfied)**:
+      - Get instructions:
+        ```bash
+        openspec instructions <artifact-id> --change "<name>" --json
+        ```
+      - The instructions JSON includes:
+        - `context`: Project background (constraints for you - do NOT include in output)
+        - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
+        - `template`: The structure to use for your output file
+        - `instruction`: Schema-specific guidance for this artifact type
+        - `outputPath`: Where to write the artifact
+        - `dependencies`: Completed artifacts to read for context
+      - Read any completed dependency files for context
+      - Create the artifact file using `template` as the structure
+      - Apply `context` and `rules` as constraints - but do NOT copy them into the file
+      - Show brief progress: "Created <artifact-id>"
+
+   b. **Continue until all `applyRequires` artifacts are complete**
+      - After creating each artifact, re-run `openspec status --change "<name>" --json`
+      - Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array
+      - Stop when all `applyRequires` artifacts are done
+
+   c. **If an artifact requires user input** (unclear context):
+      - Use **AskUserQuestion tool** to clarify
+      - Then continue with creation
+
+5. **Show final status**
+   ```bash
+   openspec status --change "<name>"
+   ```
+
+**Output**
+
+After completing all artifacts, summarize:
+- Change name and location
+- List of artifacts created with brief descriptions
+- What's ready: "All artifacts created! Ready for implementation."
+- Prompt: "Run `/opsx:apply` or ask me to implement to start working on the tasks."
+
+**Artifact Creation Guidelines**
+
+- Follow the `instruction` field from `openspec instructions` for each artifact type
+- The schema defines what each artifact should contain - follow it
+- Read dependency artifacts for context before creating new ones
+- Use `template` as the structure for your output file - fill in its sections
+- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
+  - Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
+  - These guide what you write, but should never appear in the output
+
+**Guardrails**
+- Create ALL artifacts needed for implementation (as defined by schema's `apply.requires`)
+- Always read dependency artifacts before creating a new one
+- If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
+- If a change with that name already exists, ask if user wants to continue it or create a new one
+- Verify each artifact file exists after writing before proceeding to next
diff --git a/.gitignore b/.gitignore
index 7bd717e540..f59689b9eb 100644
--- a/.gitignore
+++ b/.gitignore
@@ -44,3 +44,5 @@ docsite/
 .superpowers
 docs/superpowers
 .claude
+.opencode
+.npmrc
diff --git a/.kilocode/skills/openspec-apply-change/SKILL.md b/.kilocode/skills/openspec-apply-change/SKILL.md
new file mode 100644
index 0000000000..70fbdb8569
--- /dev/null
+++ b/.kilocode/skills/openspec-apply-change/SKILL.md
@@ -0,0 +1,156 @@
+---
+name: openspec-apply-change
+description: Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.3.1"
+---
+
+Implement tasks from an OpenSpec change.
+
+**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **Select the change**
+
+   If a name is provided, use it. Otherwise:
+   - Infer from conversation context if the user mentioned a change
+   - Auto-select if only one active change exists
+   - If ambiguous, run `openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select
+
+   Always announce: "Using change: <name>" and how to override (e.g., `/opsx:apply <other>`).
+
+2. **Check status to understand the schema**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used (e.g., "spec-driven")
+   - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
+
+3. **Get apply instructions**
+
+   ```bash
+   openspec instructions apply --change "<name>" --json
+   ```
+
+   This returns:
+   - `contextFiles`: artifact ID -> array of concrete file paths (varies by schema - could be proposal/specs/design/tasks or spec/tests/implementation/docs)
+   - Progress (total, complete, remaining)
+   - Task list with status
+   - Dynamic instruction based on current state
+
+   **Handle states:**
+   - If `state: "blocked"` (missing artifacts): show message, suggest using openspec-continue-change
+   - If `state: "all_done"`: congratulate, suggest archive
+   - Otherwise: proceed to implementation
+
+4. **Read context files**
+
+   Read every file path listed under `contextFiles` from the apply instructions output.
+   The files depend on the schema being used:
+   - **spec-driven**: proposal, specs, design, tasks
+   - Other schemas: follow the contextFiles from CLI output
+
+5. **Show current progress**
+
+   Display:
+   - Schema being used
+   - Progress: "N/M tasks complete"
+   - Remaining tasks overview
+   - Dynamic instruction from CLI
+
+6. **Implement tasks (loop until done or blocked)**
+
+   For each pending task:
+   - Show which task is being worked on
+   - Make the code changes required
+   - Keep changes minimal and focused
+   - Mark task complete in the tasks file: `- [ ]` → `- [x]`
+   - Continue to next task
+
+   **Pause if:**
+   - Task is unclear → ask for clarification
+   - Implementation reveals a design issue → suggest updating artifacts
+   - Error or blocker encountered → report and wait for guidance
+   - User interrupts
+
+7. **On completion or pause, show status**
+
+   Display:
+   - Tasks completed this session
+   - Overall progress: "N/M tasks complete"
+   - If all done: suggest archive
+   - If paused: explain why and wait for guidance
+
+**Output During Implementation**
+
+```
+## Implementing: <change-name> (schema: <schema-name>)
+
+Working on task 3/7: <task description>
+[...implementation happening...]
+✓ Task complete
+
+Working on task 4/7: <task description>
+[...implementation happening...]
+✓ Task complete
+```
+
+**Output On Completion**
+
+```
+## Implementation Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Progress:** 7/7 tasks complete ✓
+
+### Completed This Session
+- [x] Task 1
+- [x] Task 2
+...
+
+All tasks complete! Ready to archive this change.
+```
+
+**Output On Pause (Issue Encountered)**
+
+```
+## Implementation Paused
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Progress:** 4/7 tasks complete
+
+### Issue Encountered
+<description of the issue>
+
+**Options:**
+1. <option 1>
+2. <option 2>
+3. Other approach
+
+What would you like to do?
+```
+
+**Guardrails**
+- Keep going through tasks until done or blocked
+- Always read context files before starting (from the apply instructions output)
+- If task is ambiguous, pause and ask before implementing
+- If implementation reveals issues, pause and suggest artifact updates
+- Keep code changes minimal and scoped to each task
+- Update task checkbox immediately after completing each task
+- Pause on errors, blockers, or unclear requirements - don't guess
+- Use contextFiles from CLI output, don't assume specific file names
+
+**Fluid Workflow Integration**
+
+This skill supports the "actions on a change" model:
+
+- **Can be invoked anytime**: Before all artifacts are done (if tasks exist), after partial implementation, interleaved with other actions
+- **Allows artifact updates**: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly
diff --git a/.kilocode/skills/openspec-archive-change/SKILL.md b/.kilocode/skills/openspec-archive-change/SKILL.md
new file mode 100644
index 0000000000..12e2f70e9c
--- /dev/null
+++ b/.kilocode/skills/openspec-archive-change/SKILL.md
@@ -0,0 +1,114 @@
+---
+name: openspec-archive-change
+description: Archive a completed change in the experimental workflow. Use when the user wants to finalize and archive a change after implementation is complete.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.3.1"
+---
+
+Archive a completed change in the experimental workflow.
+
+**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+
+   Show only active changes (not already archived).
+   Include the schema used for each change if available.
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Check artifact completion status**
+
+   Run `openspec status --change "<name>" --json` to check artifact completion.
+
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used
+   - `artifacts`: List of artifacts with their status (`done` or other)
+
+   **If any artifacts are not `done`:**
+   - Display warning listing incomplete artifacts
+   - Use **AskUserQuestion tool** to confirm user wants to proceed
+   - Proceed if user confirms
+
+3. **Check task completion status**
+
+   Read the tasks file (typically `tasks.md`) to check for incomplete tasks.
+
+   Count tasks marked with `- [ ]` (incomplete) vs `- [x]` (complete).
+
+   **If incomplete tasks found:**
+   - Display warning showing count of incomplete tasks
+   - Use **AskUserQuestion tool** to confirm user wants to proceed
+   - Proceed if user confirms
+
+   **If no tasks file exists:** Proceed without task-related warning.
+
+4. **Assess delta spec sync state**
+
+   Check for delta specs at `openspec/changes/<name>/specs/`. If none exist, proceed without sync prompt.
+
+   **If delta specs exist:**
+   - Compare each delta spec with its corresponding main spec at `openspec/specs/<capability>/spec.md`
+   - Determine what changes would be applied (adds, modifications, removals, renames)
+   - Show a combined summary before prompting
+
+   **Prompt options:**
+   - If changes needed: "Sync now (recommended)", "Archive without syncing"
+   - If already synced: "Archive now", "Sync anyway", "Cancel"
+
+   If user chooses sync, use Task tool (subagent_type: "general-purpose", prompt: "Use Skill tool to invoke openspec-sync-specs for change '<name>'. Delta spec analysis: <include the analyzed delta spec summary>"). Proceed to archive regardless of choice.
+
+5. **Perform the archive**
+
+   Create the archive directory if it doesn't exist:
+   ```bash
+   mkdir -p openspec/changes/archive
+   ```
+
+   Generate target name using current date: `YYYY-MM-DD-<change-name>`
+
+   **Check if target already exists:**
+   - If yes: Fail with error, suggest renaming existing archive or using different date
+   - If no: Move the change directory to archive
+
+   ```bash
+   mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
+   ```
+
+6. **Display summary**
+
+   Show archive completion summary including:
+   - Change name
+   - Schema that was used
+   - Archive location
+   - Whether specs were synced (if applicable)
+   - Note about any warnings (incomplete artifacts/tasks)
+
+**Output On Success**
+
+```
+## Archive Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** ✓ Synced to main specs (or "No delta specs" or "Sync skipped")
+
+All artifacts complete. All tasks complete.
+```
+
+**Guardrails**
+- Always prompt for change selection if not provided
+- Use artifact graph (openspec status --json) for completion checking
+- Don't block archive on warnings - just inform and confirm
+- Preserve .openspec.yaml when moving to archive (it moves with the directory)
+- Show clear summary of what happened
+- If sync is requested, use openspec-sync-specs approach (agent-driven)
+- If delta specs exist, always run the sync assessment and show the combined summary before prompting
diff --git a/.kilocode/skills/openspec-explore/SKILL.md b/.kilocode/skills/openspec-explore/SKILL.md
new file mode 100644
index 0000000000..6858d3f693
--- /dev/null
+++ b/.kilocode/skills/openspec-explore/SKILL.md
@@ -0,0 +1,288 @@
+---
+name: openspec-explore
+description: Enter explore mode - a thinking partner for exploring ideas, investigating problems, and clarifying requirements. Use when the user wants to think through something before or during a change.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.3.1"
+---
+
+Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
+
+**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing.
+
+**This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.
+
+---
+
+## The Stance
+
+- **Curious, not prescriptive** - Ask questions that emerge naturally, don't follow a script
+- **Open threads, not interrogations** - Surface multiple interesting directions and let the user follow what resonates. Don't funnel them through a single path of questions.
+- **Visual** - Use ASCII diagrams liberally when they'd help clarify thinking
+- **Adaptive** - Follow interesting threads, pivot when new information emerges
+- **Patient** - Don't rush to conclusions, let the shape of the problem emerge
+- **Grounded** - Explore the actual codebase when relevant, don't just theorize
+
+---
+
+## What You Might Do
+
+Depending on what the user brings, you might:
+
+**Explore the problem space**
+- Ask clarifying questions that emerge from what they said
+- Challenge assumptions
+- Reframe the problem
+- Find analogies
+
+**Investigate the codebase**
+- Map existing architecture relevant to the discussion
+- Find integration points
+- Identify patterns already in use
+- Surface hidden complexity
+
+**Compare options**
+- Brainstorm multiple approaches
+- Build comparison tables
+- Sketch tradeoffs
+- Recommend a path (if asked)
+
+**Visualize**
+```
+┌─────────────────────────────────────────┐
+│     Use ASCII diagrams liberally        │
+├─────────────────────────────────────────┤
+│                                         │
+│      ┌────────┐         ┌────────┐      │
+│      │ State  │────────▶│ State  │      │
+│      │   A    │         │   B    │      │
+│      └────────┘         └────────┘      │
+│                                         │
+│   System diagrams, state machines,      │
+│   data flows, architecture sketches,    │
+│   dependency graphs, comparison tables  │
+│                                         │
+└─────────────────────────────────────────┘
+```
+
+**Surface risks and unknowns**
+- Identify what could go wrong
+- Find gaps in understanding
+- Suggest spikes or investigations
+
+---
+
+## OpenSpec Awareness
+
+You have full context of the OpenSpec system. Use it naturally, don't force it.
+
+### Check for context
+
+At the start, quickly check what exists:
+```bash
+openspec list --json
+```
+
+This tells you:
+- If there are active changes
+- Their names, schemas, and status
+- What the user might be working on
+
+### When no change exists
+
+Think freely. When insights crystallize, you might offer:
+
+- "This feels solid enough to start a change. Want me to create a proposal?"
+- Or keep exploring - no pressure to formalize
+
+### When a change exists
+
+If the user mentions a change or you detect one is relevant:
+
+1. **Read existing artifacts for context**
+   - `openspec/changes/<name>/proposal.md`
+   - `openspec/changes/<name>/design.md`
+   - `openspec/changes/<name>/tasks.md`
+   - etc.
+
+2. **Reference them naturally in conversation**
+   - "Your design mentions using Redis, but we just realized SQLite fits better..."
+   - "The proposal scopes this to premium users, but we're now thinking everyone..."
+
+3. **Offer to capture when decisions are made**
+
+    | Insight Type               | Where to Capture               |
+    |----------------------------|--------------------------------|
+    | New requirement discovered | `specs/<capability>/spec.md` |
+    | Requirement changed        | `specs/<capability>/spec.md` |
+    | Design decision made       | `design.md`                  |
+    | Scope changed              | `proposal.md`                |
+    | New work identified        | `tasks.md`                   |
+    | Assumption invalidated     | Relevant artifact              |
+
+   Example offers:
+   - "That's a design decision. Capture it in design.md?"
+   - "This is a new requirement. Add it to specs?"
+   - "This changes scope. Update the proposal?"
+
+4. **The user decides** - Offer and move on. Don't pressure. Don't auto-capture.
+
+---
+
+## What You Don't Have To Do
+
+- Follow a script
+- Ask the same questions every time
+- Produce a specific artifact
+- Reach a conclusion
+- Stay on topic if a tangent is valuable
+- Be brief (this is thinking time)
+
+---
+
+## Handling Different Entry Points
+
+**User brings a vague idea:**
+```
+User: I'm thinking about adding real-time collaboration
+
+You: Real-time collab is a big space. Let me think about this...
+
+      COLLABORATION SPECTRUM
+      ════════════════════════════════════════════
+
+      Awareness          Coordination         Sync
+          │                   │                 │
+          ▼                   ▼                 ▼
+      ┌────────┐         ┌────────┐        ┌────────┐
+      │Presence│         │Cursors │        │  CRDT  │
+      │  "3    │         │ Multi  │        │Conflict│
+      │online" │         │ select │        │  free  │
+      └────────┘         └────────┘        └────────┘
+          │                   │                 │
+       trivial            moderate           complex
+
+      Where's your head at?
+```
+
+**User brings a specific problem:**
+```
+User: The auth system is a mess
+
+You: [reads codebase]
+
+     ┌─────────────────────────────────────────────┐
+     │              CURRENT AUTH FLOW              │
+     └─────────────────────────────────────────────┘
+                        │
+          ┌─────────────┼─────────────┐
+          ▼             ▼             ▼
+     ┌─────────┐  ┌─────────┐  ┌─────────┐
+     │ Google  │  │  GitHub │  │  Email  │
+     │  OAuth  │  │  OAuth  │  │  Magic  │
+     └────┬────┘  └────┬────┘  └────┬────┘
+          │             │             │
+          └─────────────┼─────────────┘
+                        ▼
+                  ┌───────────┐
+                  │  Session  │
+                  └─────┬─────┘
+                        │
+                        ▼
+                  ┌───────────┐
+                  │   Perms   │
+                  └───────────┘
+
+     I see three tangles. Which one's burning?
+```
+
+**User is stuck mid-implementation:**
+```
+User: /opsx:explore add-auth-system
+      The OAuth integration is more complex than expected
+
+You: [reads change artifacts]
+
+     You're on task 4: "Implement OAuth flow"
+
+     Let me trace what's involved...
+
+     [draws diagram, explores options, suggests paths]
+
+     Want to update the design to reflect this?
+     Or add a spike task to investigate?
+```
+
+**User wants to compare options:**
+```
+User: Should we use Postgres or SQLite?
+
+You: Generic answer is boring. What's the context?
+
+User: A CLI tool that tracks local dev environments
+
+You: That changes everything.
+
+     ┌─────────────────────────────────────────────────┐
+     │          CLI TOOL DATA STORAGE                  │
+     └─────────────────────────────────────────────────┘
+
+     Key constraints:
+     • No daemon running
+     • Must work offline
+     • Single user
+
+                  SQLite          Postgres
+     Deployment   embedded ✓      needs server ✗
+     Offline      yes ✓           no ✗
+     Single file  yes ✓           no ✗
+
+     SQLite. Not even close.
+
+     Unless... is there a sync component?
+```
+
+---
+
+## Ending Discovery
+
+There's no required ending. Discovery might:
+
+- **Flow into a proposal**: "Ready to start? I can create a change proposal."
+- **Result in artifact updates**: "Updated design.md with these decisions"
+- **Just provide clarity**: User has what they need, moves on
+- **Continue later**: "We can pick this up anytime"
+
+When it feels like things are crystallizing, you might summarize:
+
+```
+## What We Figured Out
+
+**The problem**: [crystallized understanding]
+
+**The approach**: [if one emerged]
+
+**Open questions**: [if any remain]
+
+**Next steps** (if ready):
+- Create a change proposal
+- Keep exploring: just keep talking
+```
+
+But this summary is optional. Sometimes the thinking IS the value.
+
+---
+
+## Guardrails
+
+- **Don't implement** - Never write code or implement features. Creating OpenSpec artifacts is fine, writing application code is not.
+- **Don't fake understanding** - If something is unclear, dig deeper
+- **Don't rush** - Discovery is thinking time, not task time
+- **Don't force structure** - Let patterns emerge naturally
+- **Don't auto-capture** - Offer to save insights, don't just do it
+- **Do visualize** - A good diagram is worth many paragraphs
+- **Do explore the codebase** - Ground discussions in reality
+- **Do question assumptions** - Including the user's and your own
diff --git a/.kilocode/skills/openspec-propose/SKILL.md b/.kilocode/skills/openspec-propose/SKILL.md
new file mode 100644
index 0000000000..4b7e204184
--- /dev/null
+++ b/.kilocode/skills/openspec-propose/SKILL.md
@@ -0,0 +1,110 @@
+---
+name: openspec-propose
+description: Propose a new change with all artifacts generated in one step. Use when the user wants to quickly describe what they want to build and get a complete proposal with design, specs, and tasks ready for implementation.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.3.1"
+---
+
+Propose a new change - create the change and generate all artifacts in one step.
+
+I'll create a change with artifacts:
+- proposal.md (what & why)
+- design.md (how)
+- tasks.md (implementation steps)
+
+When ready to implement, run /opsx:apply
+
+---
+
+**Input**: The user's request should include a change name (kebab-case) OR a description of what they want to build.
+
+**Steps**
+
+1. **If no clear input provided, ask what they want to build**
+
+   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+   > "What change do you want to work on? Describe what you want to build or fix."
+
+   From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
+
+   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
+
+2. **Create the change directory**
+   ```bash
+   openspec new change "<name>"
+   ```
+   This creates a scaffolded change at `openspec/changes/<name>/` with `.openspec.yaml`.
+
+3. **Get the artifact build order**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to get:
+   - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
+   - `artifacts`: list of all artifacts with their status and dependencies
+
+4. **Create artifacts in sequence until apply-ready**
+
+   Use the **TodoWrite tool** to track progress through the artifacts.
+
+   Loop through artifacts in dependency order (artifacts with no pending dependencies first):
+
+   a. **For each artifact that is `ready` (dependencies satisfied)**:
+      - Get instructions:
+        ```bash
+        openspec instructions <artifact-id> --change "<name>" --json
+        ```
+      - The instructions JSON includes:
+        - `context`: Project background (constraints for you - do NOT include in output)
+        - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
+        - `template`: The structure to use for your output file
+        - `instruction`: Schema-specific guidance for this artifact type
+        - `outputPath`: Where to write the artifact
+        - `dependencies`: Completed artifacts to read for context
+      - Read any completed dependency files for context
+      - Create the artifact file using `template` as the structure
+      - Apply `context` and `rules` as constraints - but do NOT copy them into the file
+      - Show brief progress: "Created <artifact-id>"
+
+   b. **Continue until all `applyRequires` artifacts are complete**
+      - After creating each artifact, re-run `openspec status --change "<name>" --json`
+      - Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array
+      - Stop when all `applyRequires` artifacts are done
+
+   c. **If an artifact requires user input** (unclear context):
+      - Use **AskUserQuestion tool** to clarify
+      - Then continue with creation
+
+5. **Show final status**
+   ```bash
+   openspec status --change "<name>"
+   ```
+
+**Output**
+
+After completing all artifacts, summarize:
+- Change name and location
+- List of artifacts created with brief descriptions
+- What's ready: "All artifacts created! Ready for implementation."
+- Prompt: "Run `/opsx:apply` or ask me to implement to start working on the tasks."
+
+**Artifact Creation Guidelines**
+
+- Follow the `instruction` field from `openspec instructions` for each artifact type
+- The schema defines what each artifact should contain - follow it
+- Read dependency artifacts for context before creating new ones
+- Use `template` as the structure for your output file - fill in its sections
+- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
+  - Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
+  - These guide what you write, but should never appear in the output
+
+**Guardrails**
+- Create ALL artifacts needed for implementation (as defined by schema's `apply.requires`)
+- Always read dependency artifacts before creating a new one
+- If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
+- If a change with that name already exists, ask if user wants to continue it or create a new one
+- Verify each artifact file exists after writing before proceeding to next
diff --git a/.kilocode/workflows/opsx-apply.md b/.kilocode/workflows/opsx-apply.md
new file mode 100644
index 0000000000..a10693a5e2
--- /dev/null
+++ b/.kilocode/workflows/opsx-apply.md
@@ -0,0 +1,145 @@
+Implement tasks from an OpenSpec change.
+
+**Input**: Optionally specify a change name (e.g., `/opsx:apply add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **Select the change**
+
+   If a name is provided, use it. Otherwise:
+   - Infer from conversation context if the user mentioned a change
+   - Auto-select if only one active change exists
+   - If ambiguous, run `openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select
+
+   Always announce: "Using change: <name>" and how to override (e.g., `/opsx:apply <other>`).
+
+2. **Check status to understand the schema**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used (e.g., "spec-driven")
+   - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
+
+3. **Get apply instructions**
+
+   ```bash
+   openspec instructions apply --change "<name>" --json
+   ```
+
+   This returns:
+   - `contextFiles`: artifact ID -> array of concrete file paths (varies by schema)
+   - Progress (total, complete, remaining)
+   - Task list with status
+   - Dynamic instruction based on current state
+
+   **Handle states:**
+   - If `state: "blocked"` (missing artifacts): show message, suggest using `/opsx:continue`
+   - If `state: "all_done"`: congratulate, suggest archive
+   - Otherwise: proceed to implementation
+
+4. **Read context files**
+
+   Read every file path listed under `contextFiles` from the apply instructions output.
+   The files depend on the schema being used:
+   - **spec-driven**: proposal, specs, design, tasks
+   - Other schemas: follow the contextFiles from CLI output
+
+5. **Show current progress**
+
+   Display:
+   - Schema being used
+   - Progress: "N/M tasks complete"
+   - Remaining tasks overview
+   - Dynamic instruction from CLI
+
+6. **Implement tasks (loop until done or blocked)**
+
+   For each pending task:
+   - Show which task is being worked on
+   - Make the code changes required
+   - Keep changes minimal and focused
+   - Mark task complete in the tasks file: `- [ ]` → `- [x]`
+   - Continue to next task
+
+   **Pause if:**
+   - Task is unclear → ask for clarification
+   - Implementation reveals a design issue → suggest updating artifacts
+   - Error or blocker encountered → report and wait for guidance
+   - User interrupts
+
+7. **On completion or pause, show status**
+
+   Display:
+   - Tasks completed this session
+   - Overall progress: "N/M tasks complete"
+   - If all done: suggest archive
+   - If paused: explain why and wait for guidance
+
+**Output During Implementation**
+
+```
+## Implementing: <change-name> (schema: <schema-name>)
+
+Working on task 3/7: <task description>
+[...implementation happening...]
+✓ Task complete
+
+Working on task 4/7: <task description>
+[...implementation happening...]
+✓ Task complete
+```
+
+**Output On Completion**
+
+```
+## Implementation Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Progress:** 7/7 tasks complete ✓
+
+### Completed This Session
+- [x] Task 1
+- [x] Task 2
+...
+
+All tasks complete! You can archive this change with `/opsx:archive`.
+```
+
+**Output On Pause (Issue Encountered)**
+
+```
+## Implementation Paused
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Progress:** 4/7 tasks complete
+
+### Issue Encountered
+<description of the issue>
+
+**Options:**
+1. <option 1>
+2. <option 2>
+3. Other approach
+
+What would you like to do?
+```
+
+**Guardrails**
+- Keep going through tasks until done or blocked
+- Always read context files before starting (from the apply instructions output)
+- If task is ambiguous, pause and ask before implementing
+- If implementation reveals issues, pause and suggest artifact updates
+- Keep code changes minimal and scoped to each task
+- Update task checkbox immediately after completing each task
+- Pause on errors, blockers, or unclear requirements - don't guess
+- Use contextFiles from CLI output, don't assume specific file names
+
+**Fluid Workflow Integration**
+
+This skill supports the "actions on a change" model:
+
+- **Can be invoked anytime**: Before all artifacts are done (if tasks exist), after partial implementation, interleaved with other actions
+- **Allows artifact updates**: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly
diff --git a/.kilocode/workflows/opsx-archive.md b/.kilocode/workflows/opsx-archive.md
new file mode 100644
index 0000000000..46def164ca
--- /dev/null
+++ b/.kilocode/workflows/opsx-archive.md
@@ -0,0 +1,150 @@
+Archive a completed change in the experimental workflow.
+
+**Input**: Optionally specify a change name after `/opsx:archive` (e.g., `/opsx:archive add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+
+   Show only active changes (not already archived).
+   Include the schema used for each change if available.
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Check artifact completion status**
+
+   Run `openspec status --change "<name>" --json` to check artifact completion.
+
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used
+   - `artifacts`: List of artifacts with their status (`done` or other)
+
+   **If any artifacts are not `done`:**
+   - Display warning listing incomplete artifacts
+   - Prompt user for confirmation to continue
+   - Proceed if user confirms
+
+3. **Check task completion status**
+
+   Read the tasks file (typically `tasks.md`) to check for incomplete tasks.
+
+   Count tasks marked with `- [ ]` (incomplete) vs `- [x]` (complete).
+
+   **If incomplete tasks found:**
+   - Display warning showing count of incomplete tasks
+   - Prompt user for confirmation to continue
+   - Proceed if user confirms
+
+   **If no tasks file exists:** Proceed without task-related warning.
+
+4. **Assess delta spec sync state**
+
+   Check for delta specs at `openspec/changes/<name>/specs/`. If none exist, proceed without sync prompt.
+
+   **If delta specs exist:**
+   - Compare each delta spec with its corresponding main spec at `openspec/specs/<capability>/spec.md`
+   - Determine what changes would be applied (adds, modifications, removals, renames)
+   - Show a combined summary before prompting
+
+   **Prompt options:**
+   - If changes needed: "Sync now (recommended)", "Archive without syncing"
+   - If already synced: "Archive now", "Sync anyway", "Cancel"
+
+   If user chooses sync, use Task tool (subagent_type: "general-purpose", prompt: "Use Skill tool to invoke openspec-sync-specs for change '<name>'. Delta spec analysis: <include the analyzed delta spec summary>"). Proceed to archive regardless of choice.
+
+5. **Perform the archive**
+
+   Create the archive directory if it doesn't exist:
+   ```bash
+   mkdir -p openspec/changes/archive
+   ```
+
+   Generate target name using current date: `YYYY-MM-DD-<change-name>`
+
+   **Check if target already exists:**
+   - If yes: Fail with error, suggest renaming existing archive or using different date
+   - If no: Move the change directory to archive
+
+   ```bash
+   mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
+   ```
+
+6. **Display summary**
+
+   Show archive completion summary including:
+   - Change name
+   - Schema that was used
+   - Archive location
+   - Spec sync status (synced / sync skipped / no delta specs)
+   - Note about any warnings (incomplete artifacts/tasks)
+
+**Output On Success**
+
+```
+## Archive Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** ✓ Synced to main specs
+
+All artifacts complete. All tasks complete.
+```
+
+**Output On Success (No Delta Specs)**
+
+```
+## Archive Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** No delta specs
+
+All artifacts complete. All tasks complete.
+```
+
+**Output On Success With Warnings**
+
+```
+## Archive Complete (with warnings)
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** Sync skipped (user chose to skip)
+
+**Warnings:**
+- Archived with 2 incomplete artifacts
+- Archived with 3 incomplete tasks
+- Delta spec sync was skipped (user chose to skip)
+
+Review the archive if this was not intentional.
+```
+
+**Output On Error (Archive Exists)**
+
+```
+## Archive Failed
+
+**Change:** <change-name>
+**Target:** openspec/changes/archive/YYYY-MM-DD-<name>/
+
+Target archive directory already exists.
+
+**Options:**
+1. Rename the existing archive
+2. Delete the existing archive if it's a duplicate
+3. Wait until a different date to archive
+```
+
+**Guardrails**
+- Always prompt for change selection if not provided
+- Use artifact graph (openspec status --json) for completion checking
+- Don't block archive on warnings - just inform and confirm
+- Preserve .openspec.yaml when moving to archive (it moves with the directory)
+- Show clear summary of what happened
+- If sync is requested, use the Skill tool to invoke `openspec-sync-specs` (agent-driven)
+- If delta specs exist, always run the sync assessment and show the combined summary before prompting
diff --git a/.kilocode/workflows/opsx-explore.md b/.kilocode/workflows/opsx-explore.md
new file mode 100644
index 0000000000..f4debae1a3
--- /dev/null
+++ b/.kilocode/workflows/opsx-explore.md
@@ -0,0 +1,166 @@
+Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
+
+**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing.
+
+**This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.
+
+**Input**: The argument after `/opsx:explore` is whatever the user wants to think about. Could be:
+- A vague idea: "real-time collaboration"
+- A specific problem: "the auth system is getting unwieldy"
+- A change name: "add-dark-mode" (to explore in context of that change)
+- A comparison: "postgres vs sqlite for this"
+- Nothing (just enter explore mode)
+
+---
+
+## The Stance
+
+- **Curious, not prescriptive** - Ask questions that emerge naturally, don't follow a script
+- **Open threads, not interrogations** - Surface multiple interesting directions and let the user follow what resonates. Don't funnel them through a single path of questions.
+- **Visual** - Use ASCII diagrams liberally when they'd help clarify thinking
+- **Adaptive** - Follow interesting threads, pivot when new information emerges
+- **Patient** - Don't rush to conclusions, let the shape of the problem emerge
+- **Grounded** - Explore the actual codebase when relevant, don't just theorize
+
+---
+
+## What You Might Do
+
+Depending on what the user brings, you might:
+
+**Explore the problem space**
+- Ask clarifying questions that emerge from what they said
+- Challenge assumptions
+- Reframe the problem
+- Find analogies
+
+**Investigate the codebase**
+- Map existing architecture relevant to the discussion
+- Find integration points
+- Identify patterns already in use
+- Surface hidden complexity
+
+**Compare options**
+- Brainstorm multiple approaches
+- Build comparison tables
+- Sketch tradeoffs
+- Recommend a path (if asked)
+
+**Visualize**
+```
+┌─────────────────────────────────────────┐
+│     Use ASCII diagrams liberally        │
+├─────────────────────────────────────────┤
+│                                         │
+│      ┌────────┐         ┌────────┐      │
+│      │ State  │────────▶│ State  │      │
+│      │   A    │         │   B    │      │
+│      └────────┘         └────────┘      │
+│                                         │
+│   System diagrams, state machines,      │
+│   data flows, architecture sketches,    │
+│   dependency graphs, comparison tables  │
+│                                         │
+└─────────────────────────────────────────┘
+```
+
+**Surface risks and unknowns**
+- Identify what could go wrong
+- Find gaps in understanding
+- Suggest spikes or investigations
+
+---
+
+## OpenSpec Awareness
+
+You have full context of the OpenSpec system. Use it naturally, don't force it.
+
+### Check for context
+
+At the start, quickly check what exists:
+```bash
+openspec list --json
+```
+
+This tells you:
+- If there are active changes
+- Their names, schemas, and status
+- What the user might be working on
+
+If the user mentioned a specific change name, read its artifacts for context.
+
+### When no change exists
+
+Think freely. When insights crystallize, you might offer:
+
+- "This feels solid enough to start a change. Want me to create a proposal?"
+- Or keep exploring - no pressure to formalize
+
+### When a change exists
+
+If the user mentions a change or you detect one is relevant:
+
+1. **Read existing artifacts for context**
+   - `openspec/changes/<name>/proposal.md`
+   - `openspec/changes/<name>/design.md`
+   - `openspec/changes/<name>/tasks.md`
+   - etc.
+
+2. **Reference them naturally in conversation**
+   - "Your design mentions using Redis, but we just realized SQLite fits better..."
+   - "The proposal scopes this to premium users, but we're now thinking everyone..."
+
+3. **Offer to capture when decisions are made**
+
+    | Insight Type               | Where to Capture               |
+    |----------------------------|--------------------------------|
+    | New requirement discovered | `specs/<capability>/spec.md` |
+    | Requirement changed        | `specs/<capability>/spec.md` |
+    | Design decision made       | `design.md`                  |
+    | Scope changed              | `proposal.md`                |
+    | New work identified        | `tasks.md`                   |
+    | Assumption invalidated     | Relevant artifact              |
+
+   Example offers:
+   - "That's a design decision. Capture it in design.md?"
+   - "This is a new requirement. Add it to specs?"
+   - "This changes scope. Update the proposal?"
+
+4. **The user decides** - Offer and move on. Don't pressure. Don't auto-capture.
+
+---
+
+## What You Don't Have To Do
+
+- Follow a script
+- Ask the same questions every time
+- Produce a specific artifact
+- Reach a conclusion
+- Stay on topic if a tangent is valuable
+- Be brief (this is thinking time)
+
+---
+
+## Ending Discovery
+
+There's no required ending. Discovery might:
+
+- **Flow into a proposal**: "Ready to start? I can create a change proposal."
+- **Result in artifact updates**: "Updated design.md with these decisions"
+- **Just provide clarity**: User has what they need, moves on
+- **Continue later**: "We can pick this up anytime"
+
+When things crystallize, you might offer a summary - but it's optional. Sometimes the thinking IS the value.
+
+---
+
+## Guardrails
+
+- **Don't implement** - Never write code or implement features. Creating OpenSpec artifacts is fine, writing application code is not.
+- **Don't fake understanding** - If something is unclear, dig deeper
+- **Don't rush** - Discovery is thinking time, not task time
+- **Don't force structure** - Let patterns emerge naturally
+- **Don't auto-capture** - Offer to save insights, don't just do it
+- **Do visualize** - A good diagram is worth many paragraphs
+- **Do explore the codebase** - Ground discussions in reality
+- **Do question assumptions** - Including the user's and your own
diff --git a/.kilocode/workflows/opsx-propose.md b/.kilocode/workflows/opsx-propose.md
new file mode 100644
index 0000000000..5085afc97c
--- /dev/null
+++ b/.kilocode/workflows/opsx-propose.md
@@ -0,0 +1,99 @@
+Propose a new change - create the change and generate all artifacts in one step.
+
+I'll create a change with artifacts:
+- proposal.md (what & why)
+- design.md (how)
+- tasks.md (implementation steps)
+
+When ready to implement, run /opsx:apply
+
+---
+
+**Input**: The argument after `/opsx:propose` is the change name (kebab-case), OR a description of what the user wants to build.
+
+**Steps**
+
+1. **If no input provided, ask what they want to build**
+
+   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+   > "What change do you want to work on? Describe what you want to build or fix."
+
+   From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
+
+   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
+
+2. **Create the change directory**
+   ```bash
+   openspec new change "<name>"
+   ```
+   This creates a scaffolded change at `openspec/changes/<name>/` with `.openspec.yaml`.
+
+3. **Get the artifact build order**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to get:
+   - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
+   - `artifacts`: list of all artifacts with their status and dependencies
+
+4. **Create artifacts in sequence until apply-ready**
+
+   Use the **TodoWrite tool** to track progress through the artifacts.
+
+   Loop through artifacts in dependency order (artifacts with no pending dependencies first):
+
+   a. **For each artifact that is `ready` (dependencies satisfied)**:
+      - Get instructions:
+        ```bash
+        openspec instructions <artifact-id> --change "<name>" --json
+        ```
+      - The instructions JSON includes:
+        - `context`: Project background (constraints for you - do NOT include in output)
+        - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
+        - `template`: The structure to use for your output file
+        - `instruction`: Schema-specific guidance for this artifact type
+        - `outputPath`: Where to write the artifact
+        - `dependencies`: Completed artifacts to read for context
+      - Read any completed dependency files for context
+      - Create the artifact file using `template` as the structure
+      - Apply `context` and `rules` as constraints - but do NOT copy them into the file
+      - Show brief progress: "Created <artifact-id>"
+
+   b. **Continue until all `applyRequires` artifacts are complete**
+      - After creating each artifact, re-run `openspec status --change "<name>" --json`
+      - Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array
+      - Stop when all `applyRequires` artifacts are done
+
+   c. **If an artifact requires user input** (unclear context):
+      - Use **AskUserQuestion tool** to clarify
+      - Then continue with creation
+
+5. **Show final status**
+   ```bash
+   openspec status --change "<name>"
+   ```
+
+**Output**
+
+After completing all artifacts, summarize:
+- Change name and location
+- List of artifacts created with brief descriptions
+- What's ready: "All artifacts created! Ready for implementation."
+- Prompt: "Run `/opsx:apply` to start implementing."
+
+**Artifact Creation Guidelines**
+
+- Follow the `instruction` field from `openspec instructions` for each artifact type
+- The schema defines what each artifact should contain - follow it
+- Read dependency artifacts for context before creating new ones
+- Use `template` as the structure for your output file - fill in its sections
+- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
+  - Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
+  - These guide what you write, but should never appear in the output
+
+**Guardrails**
+- Create ALL artifacts needed for implementation (as defined by schema's `apply.requires`)
+- Always read dependency artifacts before creating a new one
+- If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
+- If a change with that name already exists, ask if user wants to continue it or create a new one
+- Verify each artifact file exists after writing before proceeding to next
diff --git a/.roo/commands/opsx-apply.md b/.roo/commands/opsx-apply.md
new file mode 100644
index 0000000000..37a78e612d
--- /dev/null
+++ b/.roo/commands/opsx-apply.md
@@ -0,0 +1,149 @@
+# OPSX: Apply
+
+Implement tasks from an OpenSpec change (Experimental)
+
+Implement tasks from an OpenSpec change.
+
+**Input**: Optionally specify a change name (e.g., `/opsx:apply add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **Select the change**
+
+   If a name is provided, use it. Otherwise:
+   - Infer from conversation context if the user mentioned a change
+   - Auto-select if only one active change exists
+   - If ambiguous, run `openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select
+
+   Always announce: "Using change: <name>" and how to override (e.g., `/opsx:apply <other>`).
+
+2. **Check status to understand the schema**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used (e.g., "spec-driven")
+   - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
+
+3. **Get apply instructions**
+
+   ```bash
+   openspec instructions apply --change "<name>" --json
+   ```
+
+   This returns:
+   - `contextFiles`: artifact ID -> array of concrete file paths (varies by schema)
+   - Progress (total, complete, remaining)
+   - Task list with status
+   - Dynamic instruction based on current state
+
+   **Handle states:**
+   - If `state: "blocked"` (missing artifacts): show message, suggest using `/opsx:continue`
+   - If `state: "all_done"`: congratulate, suggest archive
+   - Otherwise: proceed to implementation
+
+4. **Read context files**
+
+   Read every file path listed under `contextFiles` from the apply instructions output.
+   The files depend on the schema being used:
+   - **spec-driven**: proposal, specs, design, tasks
+   - Other schemas: follow the contextFiles from CLI output
+
+5. **Show current progress**
+
+   Display:
+   - Schema being used
+   - Progress: "N/M tasks complete"
+   - Remaining tasks overview
+   - Dynamic instruction from CLI
+
+6. **Implement tasks (loop until done or blocked)**
+
+   For each pending task:
+   - Show which task is being worked on
+   - Make the code changes required
+   - Keep changes minimal and focused
+   - Mark task complete in the tasks file: `- [ ]` → `- [x]`
+   - Continue to next task
+
+   **Pause if:**
+   - Task is unclear → ask for clarification
+   - Implementation reveals a design issue → suggest updating artifacts
+   - Error or blocker encountered → report and wait for guidance
+   - User interrupts
+
+7. **On completion or pause, show status**
+
+   Display:
+   - Tasks completed this session
+   - Overall progress: "N/M tasks complete"
+   - If all done: suggest archive
+   - If paused: explain why and wait for guidance
+
+**Output During Implementation**
+
+```
+## Implementing: <change-name> (schema: <schema-name>)
+
+Working on task 3/7: <task description>
+[...implementation happening...]
+✓ Task complete
+
+Working on task 4/7: <task description>
+[...implementation happening...]
+✓ Task complete
+```
+
+**Output On Completion**
+
+```
+## Implementation Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Progress:** 7/7 tasks complete ✓
+
+### Completed This Session
+- [x] Task 1
+- [x] Task 2
+...
+
+All tasks complete! You can archive this change with `/opsx:archive`.
+```
+
+**Output On Pause (Issue Encountered)**
+
+```
+## Implementation Paused
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Progress:** 4/7 tasks complete
+
+### Issue Encountered
+<description of the issue>
+
+**Options:**
+1. <option 1>
+2. <option 2>
+3. Other approach
+
+What would you like to do?
+```
+
+**Guardrails**
+- Keep going through tasks until done or blocked
+- Always read context files before starting (from the apply instructions output)
+- If task is ambiguous, pause and ask before implementing
+- If implementation reveals issues, pause and suggest artifact updates
+- Keep code changes minimal and scoped to each task
+- Update task checkbox immediately after completing each task
+- Pause on errors, blockers, or unclear requirements - don't guess
+- Use contextFiles from CLI output, don't assume specific file names
+
+**Fluid Workflow Integration**
+
+This skill supports the "actions on a change" model:
+
+- **Can be invoked anytime**: Before all artifacts are done (if tasks exist), after partial implementation, interleaved with other actions
+- **Allows artifact updates**: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly
diff --git a/.roo/commands/opsx-archive.md b/.roo/commands/opsx-archive.md
new file mode 100644
index 0000000000..c38d6f6ef9
--- /dev/null
+++ b/.roo/commands/opsx-archive.md
@@ -0,0 +1,154 @@
+# OPSX: Archive
+
+Archive a completed change in the experimental workflow
+
+Archive a completed change in the experimental workflow.
+
+**Input**: Optionally specify a change name after `/opsx:archive` (e.g., `/opsx:archive add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+
+   Show only active changes (not already archived).
+   Include the schema used for each change if available.
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Check artifact completion status**
+
+   Run `openspec status --change "<name>" --json` to check artifact completion.
+
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used
+   - `artifacts`: List of artifacts with their status (`done` or other)
+
+   **If any artifacts are not `done`:**
+   - Display warning listing incomplete artifacts
+   - Prompt user for confirmation to continue
+   - Proceed if user confirms
+
+3. **Check task completion status**
+
+   Read the tasks file (typically `tasks.md`) to check for incomplete tasks.
+
+   Count tasks marked with `- [ ]` (incomplete) vs `- [x]` (complete).
+
+   **If incomplete tasks found:**
+   - Display warning showing count of incomplete tasks
+   - Prompt user for confirmation to continue
+   - Proceed if user confirms
+
+   **If no tasks file exists:** Proceed without task-related warning.
+
+4. **Assess delta spec sync state**
+
+   Check for delta specs at `openspec/changes/<name>/specs/`. If none exist, proceed without sync prompt.
+
+   **If delta specs exist:**
+   - Compare each delta spec with its corresponding main spec at `openspec/specs/<capability>/spec.md`
+   - Determine what changes would be applied (adds, modifications, removals, renames)
+   - Show a combined summary before prompting
+
+   **Prompt options:**
+   - If changes needed: "Sync now (recommended)", "Archive without syncing"
+   - If already synced: "Archive now", "Sync anyway", "Cancel"
+
+   If user chooses sync, use Task tool (subagent_type: "general-purpose", prompt: "Use Skill tool to invoke openspec-sync-specs for change '<name>'. Delta spec analysis: <include the analyzed delta spec summary>"). Proceed to archive regardless of choice.
+
+5. **Perform the archive**
+
+   Create the archive directory if it doesn't exist:
+   ```bash
+   mkdir -p openspec/changes/archive
+   ```
+
+   Generate target name using current date: `YYYY-MM-DD-<change-name>`
+
+   **Check if target already exists:**
+   - If yes: Fail with error, suggest renaming existing archive or using different date
+   - If no: Move the change directory to archive
+
+   ```bash
+   mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
+   ```
+
+6. **Display summary**
+
+   Show archive completion summary including:
+   - Change name
+   - Schema that was used
+   - Archive location
+   - Spec sync status (synced / sync skipped / no delta specs)
+   - Note about any warnings (incomplete artifacts/tasks)
+
+**Output On Success**
+
+```
+## Archive Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** ✓ Synced to main specs
+
+All artifacts complete. All tasks complete.
+```
+
+**Output On Success (No Delta Specs)**
+
+```
+## Archive Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** No delta specs
+
+All artifacts complete. All tasks complete.
+```
+
+**Output On Success With Warnings**
+
+```
+## Archive Complete (with warnings)
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** Sync skipped (user chose to skip)
+
+**Warnings:**
+- Archived with 2 incomplete artifacts
+- Archived with 3 incomplete tasks
+- Delta spec sync was skipped (user chose to skip)
+
+Review the archive if this was not intentional.
+```
+
+**Output On Error (Archive Exists)**
+
+```
+## Archive Failed
+
+**Change:** <change-name>
+**Target:** openspec/changes/archive/YYYY-MM-DD-<name>/
+
+Target archive directory already exists.
+
+**Options:**
+1. Rename the existing archive
+2. Delete the existing archive if it's a duplicate
+3. Wait until a different date to archive
+```
+
+**Guardrails**
+- Always prompt for change selection if not provided
+- Use artifact graph (openspec status --json) for completion checking
+- Don't block archive on warnings - just inform and confirm
+- Preserve .openspec.yaml when moving to archive (it moves with the directory)
+- Show clear summary of what happened
+- If sync is requested, use the Skill tool to invoke `openspec-sync-specs` (agent-driven)
+- If delta specs exist, always run the sync assessment and show the combined summary before prompting
diff --git a/.roo/commands/opsx-explore.md b/.roo/commands/opsx-explore.md
new file mode 100644
index 0000000000..0c5f0347ce
--- /dev/null
+++ b/.roo/commands/opsx-explore.md
@@ -0,0 +1,170 @@
+# OPSX: Explore
+
+Enter explore mode - think through ideas, investigate problems, clarify requirements
+
+Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
+
+**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing.
+
+**This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.
+
+**Input**: The argument after `/opsx:explore` is whatever the user wants to think about. Could be:
+- A vague idea: "real-time collaboration"
+- A specific problem: "the auth system is getting unwieldy"
+- A change name: "add-dark-mode" (to explore in context of that change)
+- A comparison: "postgres vs sqlite for this"
+- Nothing (just enter explore mode)
+
+---
+
+## The Stance
+
+- **Curious, not prescriptive** - Ask questions that emerge naturally, don't follow a script
+- **Open threads, not interrogations** - Surface multiple interesting directions and let the user follow what resonates. Don't funnel them through a single path of questions.
+- **Visual** - Use ASCII diagrams liberally when they'd help clarify thinking
+- **Adaptive** - Follow interesting threads, pivot when new information emerges
+- **Patient** - Don't rush to conclusions, let the shape of the problem emerge
+- **Grounded** - Explore the actual codebase when relevant, don't just theorize
+
+---
+
+## What You Might Do
+
+Depending on what the user brings, you might:
+
+**Explore the problem space**
+- Ask clarifying questions that emerge from what they said
+- Challenge assumptions
+- Reframe the problem
+- Find analogies
+
+**Investigate the codebase**
+- Map existing architecture relevant to the discussion
+- Find integration points
+- Identify patterns already in use
+- Surface hidden complexity
+
+**Compare options**
+- Brainstorm multiple approaches
+- Build comparison tables
+- Sketch tradeoffs
+- Recommend a path (if asked)
+
+**Visualize**
+```
+┌─────────────────────────────────────────┐
+│     Use ASCII diagrams liberally        │
+├─────────────────────────────────────────┤
+│                                         │
+│      ┌────────┐         ┌────────┐      │
+│      │ State  │────────▶│ State  │      │
+│      │   A    │         │   B    │      │
+│      └────────┘         └────────┘      │
+│                                         │
+│   System diagrams, state machines,      │
+│   data flows, architecture sketches,    │
+│   dependency graphs, comparison tables  │
+│                                         │
+└─────────────────────────────────────────┘
+```
+
+**Surface risks and unknowns**
+- Identify what could go wrong
+- Find gaps in understanding
+- Suggest spikes or investigations
+
+---
+
+## OpenSpec Awareness
+
+You have full context of the OpenSpec system. Use it naturally, don't force it.
+
+### Check for context
+
+At the start, quickly check what exists:
+```bash
+openspec list --json
+```
+
+This tells you:
+- If there are active changes
+- Their names, schemas, and status
+- What the user might be working on
+
+If the user mentioned a specific change name, read its artifacts for context.
+
+### When no change exists
+
+Think freely. When insights crystallize, you might offer:
+
+- "This feels solid enough to start a change. Want me to create a proposal?"
+- Or keep exploring - no pressure to formalize
+
+### When a change exists
+
+If the user mentions a change or you detect one is relevant:
+
+1. **Read existing artifacts for context**
+   - `openspec/changes/<name>/proposal.md`
+   - `openspec/changes/<name>/design.md`
+   - `openspec/changes/<name>/tasks.md`
+   - etc.
+
+2. **Reference them naturally in conversation**
+   - "Your design mentions using Redis, but we just realized SQLite fits better..."
+   - "The proposal scopes this to premium users, but we're now thinking everyone..."
+
+3. **Offer to capture when decisions are made**
+
+    | Insight Type               | Where to Capture               |
+    |----------------------------|--------------------------------|
+    | New requirement discovered | `specs/<capability>/spec.md` |
+    | Requirement changed        | `specs/<capability>/spec.md` |
+    | Design decision made       | `design.md`                  |
+    | Scope changed              | `proposal.md`                |
+    | New work identified        | `tasks.md`                   |
+    | Assumption invalidated     | Relevant artifact              |
+
+   Example offers:
+   - "That's a design decision. Capture it in design.md?"
+   - "This is a new requirement. Add it to specs?"
+   - "This changes scope. Update the proposal?"
+
+4. **The user decides** - Offer and move on. Don't pressure. Don't auto-capture.
+
+---
+
+## What You Don't Have To Do
+
+- Follow a script
+- Ask the same questions every time
+- Produce a specific artifact
+- Reach a conclusion
+- Stay on topic if a tangent is valuable
+- Be brief (this is thinking time)
+
+---
+
+## Ending Discovery
+
+There's no required ending. Discovery might:
+
+- **Flow into a proposal**: "Ready to start? I can create a change proposal."
+- **Result in artifact updates**: "Updated design.md with these decisions"
+- **Just provide clarity**: User has what they need, moves on
+- **Continue later**: "We can pick this up anytime"
+
+When things crystallize, you might offer a summary - but it's optional. Sometimes the thinking IS the value.
+
+---
+
+## Guardrails
+
+- **Don't implement** - Never write code or implement features. Creating OpenSpec artifacts is fine, writing application code is not.
+- **Don't fake understanding** - If something is unclear, dig deeper
+- **Don't rush** - Discovery is thinking time, not task time
+- **Don't force structure** - Let patterns emerge naturally
+- **Don't auto-capture** - Offer to save insights, don't just do it
+- **Do visualize** - A good diagram is worth many paragraphs
+- **Do explore the codebase** - Ground discussions in reality
+- **Do question assumptions** - Including the user's and your own
diff --git a/.roo/commands/opsx-propose.md b/.roo/commands/opsx-propose.md
new file mode 100644
index 0000000000..6669d0d32d
--- /dev/null
+++ b/.roo/commands/opsx-propose.md
@@ -0,0 +1,103 @@
+# OPSX: Propose
+
+Propose a new change - create it and generate all artifacts in one step
+
+Propose a new change - create the change and generate all artifacts in one step.
+
+I'll create a change with artifacts:
+- proposal.md (what & why)
+- design.md (how)
+- tasks.md (implementation steps)
+
+When ready to implement, run /opsx:apply
+
+---
+
+**Input**: The argument after `/opsx:propose` is the change name (kebab-case), OR a description of what the user wants to build.
+
+**Steps**
+
+1. **If no input provided, ask what they want to build**
+
+   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+   > "What change do you want to work on? Describe what you want to build or fix."
+
+   From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
+
+   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
+
+2. **Create the change directory**
+   ```bash
+   openspec new change "<name>"
+   ```
+   This creates a scaffolded change at `openspec/changes/<name>/` with `.openspec.yaml`.
+
+3. **Get the artifact build order**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to get:
+   - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
+   - `artifacts`: list of all artifacts with their status and dependencies
+
+4. **Create artifacts in sequence until apply-ready**
+
+   Use the **TodoWrite tool** to track progress through the artifacts.
+
+   Loop through artifacts in dependency order (artifacts with no pending dependencies first):
+
+   a. **For each artifact that is `ready` (dependencies satisfied)**:
+      - Get instructions:
+        ```bash
+        openspec instructions <artifact-id> --change "<name>" --json
+        ```
+      - The instructions JSON includes:
+        - `context`: Project background (constraints for you - do NOT include in output)
+        - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
+        - `template`: The structure to use for your output file
+        - `instruction`: Schema-specific guidance for this artifact type
+        - `outputPath`: Where to write the artifact
+        - `dependencies`: Completed artifacts to read for context
+      - Read any completed dependency files for context
+      - Create the artifact file using `template` as the structure
+      - Apply `context` and `rules` as constraints - but do NOT copy them into the file
+      - Show brief progress: "Created <artifact-id>"
+
+   b. **Continue until all `applyRequires` artifacts are complete**
+      - After creating each artifact, re-run `openspec status --change "<name>" --json`
+      - Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array
+      - Stop when all `applyRequires` artifacts are done
+
+   c. **If an artifact requires user input** (unclear context):
+      - Use **AskUserQuestion tool** to clarify
+      - Then continue with creation
+
+5. **Show final status**
+   ```bash
+   openspec status --change "<name>"
+   ```
+
+**Output**
+
+After completing all artifacts, summarize:
+- Change name and location
+- List of artifacts created with brief descriptions
+- What's ready: "All artifacts created! Ready for implementation."
+- Prompt: "Run `/opsx:apply` to start implementing."
+
+**Artifact Creation Guidelines**
+
+- Follow the `instruction` field from `openspec instructions` for each artifact type
+- The schema defines what each artifact should contain - follow it
+- Read dependency artifacts for context before creating new ones
+- Use `template` as the structure for your output file - fill in its sections
+- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
+  - Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
+  - These guide what you write, but should never appear in the output
+
+**Guardrails**
+- Create ALL artifacts needed for implementation (as defined by schema's `apply.requires`)
+- Always read dependency artifacts before creating a new one
+- If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
+- If a change with that name already exists, ask if user wants to continue it or create a new one
+- Verify each artifact file exists after writing before proceeding to next
diff --git a/.roo/skills/openspec-apply-change/SKILL.md b/.roo/skills/openspec-apply-change/SKILL.md
new file mode 100644
index 0000000000..70fbdb8569
--- /dev/null
+++ b/.roo/skills/openspec-apply-change/SKILL.md
@@ -0,0 +1,156 @@
+---
+name: openspec-apply-change
+description: Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.3.1"
+---
+
+Implement tasks from an OpenSpec change.
+
+**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **Select the change**
+
+   If a name is provided, use it. Otherwise:
+   - Infer from conversation context if the user mentioned a change
+   - Auto-select if only one active change exists
+   - If ambiguous, run `openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select
+
+   Always announce: "Using change: <name>" and how to override (e.g., `/opsx:apply <other>`).
+
+2. **Check status to understand the schema**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used (e.g., "spec-driven")
+   - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
+
+3. **Get apply instructions**
+
+   ```bash
+   openspec instructions apply --change "<name>" --json
+   ```
+
+   This returns:
+   - `contextFiles`: artifact ID -> array of concrete file paths (varies by schema - could be proposal/specs/design/tasks or spec/tests/implementation/docs)
+   - Progress (total, complete, remaining)
+   - Task list with status
+   - Dynamic instruction based on current state
+
+   **Handle states:**
+   - If `state: "blocked"` (missing artifacts): show message, suggest using openspec-continue-change
+   - If `state: "all_done"`: congratulate, suggest archive
+   - Otherwise: proceed to implementation
+
+4. **Read context files**
+
+   Read every file path listed under `contextFiles` from the apply instructions output.
+   The files depend on the schema being used:
+   - **spec-driven**: proposal, specs, design, tasks
+   - Other schemas: follow the contextFiles from CLI output
+
+5. **Show current progress**
+
+   Display:
+   - Schema being used
+   - Progress: "N/M tasks complete"
+   - Remaining tasks overview
+   - Dynamic instruction from CLI
+
+6. **Implement tasks (loop until done or blocked)**
+
+   For each pending task:
+   - Show which task is being worked on
+   - Make the code changes required
+   - Keep changes minimal and focused
+   - Mark task complete in the tasks file: `- [ ]` → `- [x]`
+   - Continue to next task
+
+   **Pause if:**
+   - Task is unclear → ask for clarification
+   - Implementation reveals a design issue → suggest updating artifacts
+   - Error or blocker encountered → report and wait for guidance
+   - User interrupts
+
+7. **On completion or pause, show status**
+
+   Display:
+   - Tasks completed this session
+   - Overall progress: "N/M tasks complete"
+   - If all done: suggest archive
+   - If paused: explain why and wait for guidance
+
+**Output During Implementation**
+
+```
+## Implementing: <change-name> (schema: <schema-name>)
+
+Working on task 3/7: <task description>
+[...implementation happening...]
+✓ Task complete
+
+Working on task 4/7: <task description>
+[...implementation happening...]
+✓ Task complete
+```
+
+**Output On Completion**
+
+```
+## Implementation Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Progress:** 7/7 tasks complete ✓
+
+### Completed This Session
+- [x] Task 1
+- [x] Task 2
+...
+
+All tasks complete! Ready to archive this change.
+```
+
+**Output On Pause (Issue Encountered)**
+
+```
+## Implementation Paused
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Progress:** 4/7 tasks complete
+
+### Issue Encountered
+<description of the issue>
+
+**Options:**
+1. <option 1>
+2. <option 2>
+3. Other approach
+
+What would you like to do?
+```
+
+**Guardrails**
+- Keep going through tasks until done or blocked
+- Always read context files before starting (from the apply instructions output)
+- If task is ambiguous, pause and ask before implementing
+- If implementation reveals issues, pause and suggest artifact updates
+- Keep code changes minimal and scoped to each task
+- Update task checkbox immediately after completing each task
+- Pause on errors, blockers, or unclear requirements - don't guess
+- Use contextFiles from CLI output, don't assume specific file names
+
+**Fluid Workflow Integration**
+
+This skill supports the "actions on a change" model:
+
+- **Can be invoked anytime**: Before all artifacts are done (if tasks exist), after partial implementation, interleaved with other actions
+- **Allows artifact updates**: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly
diff --git a/.roo/skills/openspec-archive-change/SKILL.md b/.roo/skills/openspec-archive-change/SKILL.md
new file mode 100644
index 0000000000..12e2f70e9c
--- /dev/null
+++ b/.roo/skills/openspec-archive-change/SKILL.md
@@ -0,0 +1,114 @@
+---
+name: openspec-archive-change
+description: Archive a completed change in the experimental workflow. Use when the user wants to finalize and archive a change after implementation is complete.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.3.1"
+---
+
+Archive a completed change in the experimental workflow.
+
+**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+
+   Show only active changes (not already archived).
+   Include the schema used for each change if available.
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Check artifact completion status**
+
+   Run `openspec status --change "<name>" --json` to check artifact completion.
+
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used
+   - `artifacts`: List of artifacts with their status (`done` or other)
+
+   **If any artifacts are not `done`:**
+   - Display warning listing incomplete artifacts
+   - Use **AskUserQuestion tool** to confirm user wants to proceed
+   - Proceed if user confirms
+
+3. **Check task completion status**
+
+   Read the tasks file (typically `tasks.md`) to check for incomplete tasks.
+
+   Count tasks marked with `- [ ]` (incomplete) vs `- [x]` (complete).
+
+   **If incomplete tasks found:**
+   - Display warning showing count of incomplete tasks
+   - Use **AskUserQuestion tool** to confirm user wants to proceed
+   - Proceed if user confirms
+
+   **If no tasks file exists:** Proceed without task-related warning.
+
+4. **Assess delta spec sync state**
+
+   Check for delta specs at `openspec/changes/<name>/specs/`. If none exist, proceed without sync prompt.
+
+   **If delta specs exist:**
+   - Compare each delta spec with its corresponding main spec at `openspec/specs/<capability>/spec.md`
+   - Determine what changes would be applied (adds, modifications, removals, renames)
+   - Show a combined summary before prompting
+
+   **Prompt options:**
+   - If changes needed: "Sync now (recommended)", "Archive without syncing"
+   - If already synced: "Archive now", "Sync anyway", "Cancel"
+
+   If user chooses sync, use Task tool (subagent_type: "general-purpose", prompt: "Use Skill tool to invoke openspec-sync-specs for change '<name>'. Delta spec analysis: <include the analyzed delta spec summary>"). Proceed to archive regardless of choice.
+
+5. **Perform the archive**
+
+   Create the archive directory if it doesn't exist:
+   ```bash
+   mkdir -p openspec/changes/archive
+   ```
+
+   Generate target name using current date: `YYYY-MM-DD-<change-name>`
+
+   **Check if target already exists:**
+   - If yes: Fail with error, suggest renaming existing archive or using different date
+   - If no: Move the change directory to archive
+
+   ```bash
+   mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
+   ```
+
+6. **Display summary**
+
+   Show archive completion summary including:
+   - Change name
+   - Schema that was used
+   - Archive location
+   - Whether specs were synced (if applicable)
+   - Note about any warnings (incomplete artifacts/tasks)
+
+**Output On Success**
+
+```
+## Archive Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** ✓ Synced to main specs (or "No delta specs" or "Sync skipped")
+
+All artifacts complete. All tasks complete.
+```
+
+**Guardrails**
+- Always prompt for change selection if not provided
+- Use artifact graph (openspec status --json) for completion checking
+- Don't block archive on warnings - just inform and confirm
+- Preserve .openspec.yaml when moving to archive (it moves with the directory)
+- Show clear summary of what happened
+- If sync is requested, use openspec-sync-specs approach (agent-driven)
+- If delta specs exist, always run the sync assessment and show the combined summary before prompting
diff --git a/.roo/skills/openspec-explore/SKILL.md b/.roo/skills/openspec-explore/SKILL.md
new file mode 100644
index 0000000000..6858d3f693
--- /dev/null
+++ b/.roo/skills/openspec-explore/SKILL.md
@@ -0,0 +1,288 @@
+---
+name: openspec-explore
+description: Enter explore mode - a thinking partner for exploring ideas, investigating problems, and clarifying requirements. Use when the user wants to think through something before or during a change.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.3.1"
+---
+
+Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
+
+**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing.
+
+**This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.
+
+---
+
+## The Stance
+
+- **Curious, not prescriptive** - Ask questions that emerge naturally, don't follow a script
+- **Open threads, not interrogations** - Surface multiple interesting directions and let the user follow what resonates. Don't funnel them through a single path of questions.
+- **Visual** - Use ASCII diagrams liberally when they'd help clarify thinking
+- **Adaptive** - Follow interesting threads, pivot when new information emerges
+- **Patient** - Don't rush to conclusions, let the shape of the problem emerge
+- **Grounded** - Explore the actual codebase when relevant, don't just theorize
+
+---
+
+## What You Might Do
+
+Depending on what the user brings, you might:
+
+**Explore the problem space**
+- Ask clarifying questions that emerge from what they said
+- Challenge assumptions
+- Reframe the problem
+- Find analogies
+
+**Investigate the codebase**
+- Map existing architecture relevant to the discussion
+- Find integration points
+- Identify patterns already in use
+- Surface hidden complexity
+
+**Compare options**
+- Brainstorm multiple approaches
+- Build comparison tables
+- Sketch tradeoffs
+- Recommend a path (if asked)
+
+**Visualize**
+```
+┌─────────────────────────────────────────┐
+│     Use ASCII diagrams liberally        │
+├─────────────────────────────────────────┤
+│                                         │
+│      ┌────────┐         ┌────────┐      │
+│      │ State  │────────▶│ State  │      │
+│      │   A    │         │   B    │      │
+│      └────────┘         └────────┘      │
+│                                         │
+│   System diagrams, state machines,      │
+│   data flows, architecture sketches,    │
+│   dependency graphs, comparison tables  │
+│                                         │
+└─────────────────────────────────────────┘
+```
+
+**Surface risks and unknowns**
+- Identify what could go wrong
+- Find gaps in understanding
+- Suggest spikes or investigations
+
+---
+
+## OpenSpec Awareness
+
+You have full context of the OpenSpec system. Use it naturally, don't force it.
+
+### Check for context
+
+At the start, quickly check what exists:
+```bash
+openspec list --json
+```
+
+This tells you:
+- If there are active changes
+- Their names, schemas, and status
+- What the user might be working on
+
+### When no change exists
+
+Think freely. When insights crystallize, you might offer:
+
+- "This feels solid enough to start a change. Want me to create a proposal?"
+- Or keep exploring - no pressure to formalize
+
+### When a change exists
+
+If the user mentions a change or you detect one is relevant:
+
+1. **Read existing artifacts for context**
+   - `openspec/changes/<name>/proposal.md`
+   - `openspec/changes/<name>/design.md`
+   - `openspec/changes/<name>/tasks.md`
+   - etc.
+
+2. **Reference them naturally in conversation**
+   - "Your design mentions using Redis, but we just realized SQLite fits better..."
+   - "The proposal scopes this to premium users, but we're now thinking everyone..."
+
+3. **Offer to capture when decisions are made**
+
+    | Insight Type               | Where to Capture               |
+    |----------------------------|--------------------------------|
+    | New requirement discovered | `specs/<capability>/spec.md` |
+    | Requirement changed        | `specs/<capability>/spec.md` |
+    | Design decision made       | `design.md`                  |
+    | Scope changed              | `proposal.md`                |
+    | New work identified        | `tasks.md`                   |
+    | Assumption invalidated     | Relevant artifact              |
+
+   Example offers:
+   - "That's a design decision. Capture it in design.md?"
+   - "This is a new requirement. Add it to specs?"
+   - "This changes scope. Update the proposal?"
+
+4. **The user decides** - Offer and move on. Don't pressure. Don't auto-capture.
+
+---
+
+## What You Don't Have To Do
+
+- Follow a script
+- Ask the same questions every time
+- Produce a specific artifact
+- Reach a conclusion
+- Stay on topic if a tangent is valuable
+- Be brief (this is thinking time)
+
+---
+
+## Handling Different Entry Points
+
+**User brings a vague idea:**
+```
+User: I'm thinking about adding real-time collaboration
+
+You: Real-time collab is a big space. Let me think about this...
+
+      COLLABORATION SPECTRUM
+      ════════════════════════════════════════════
+
+      Awareness          Coordination         Sync
+          │                   │                 │
+          ▼                   ▼                 ▼
+      ┌────────┐         ┌────────┐        ┌────────┐
+      │Presence│         │Cursors │        │  CRDT  │
+      │  "3    │         │ Multi  │        │Conflict│
+      │online" │         │ select │        │  free  │
+      └────────┘         └────────┘        └────────┘
+          │                   │                 │
+       trivial            moderate           complex
+
+      Where's your head at?
+```
+
+**User brings a specific problem:**
+```
+User: The auth system is a mess
+
+You: [reads codebase]
+
+     ┌─────────────────────────────────────────────┐
+     │              CURRENT AUTH FLOW              │
+     └─────────────────────────────────────────────┘
+                        │
+          ┌─────────────┼─────────────┐
+          ▼             ▼             ▼
+     ┌─────────┐  ┌─────────┐  ┌─────────┐
+     │ Google  │  │  GitHub │  │  Email  │
+     │  OAuth  │  │  OAuth  │  │  Magic  │
+     └────┬────┘  └────┬────┘  └────┬────┘
+          │             │             │
+          └─────────────┼─────────────┘
+                        ▼
+                  ┌───────────┐
+                  │  Session  │
+                  └─────┬─────┘
+                        │
+                        ▼
+                  ┌───────────┐
+                  │   Perms   │
+                  └───────────┘
+
+     I see three tangles. Which one's burning?
+```
+
+**User is stuck mid-implementation:**
+```
+User: /opsx:explore add-auth-system
+      The OAuth integration is more complex than expected
+
+You: [reads change artifacts]
+
+     You're on task 4: "Implement OAuth flow"
+
+     Let me trace what's involved...
+
+     [draws diagram, explores options, suggests paths]
+
+     Want to update the design to reflect this?
+     Or add a spike task to investigate?
+```
+
+**User wants to compare options:**
+```
+User: Should we use Postgres or SQLite?
+
+You: Generic answer is boring. What's the context?
+
+User: A CLI tool that tracks local dev environments
+
+You: That changes everything.
+
+     ┌─────────────────────────────────────────────────┐
+     │          CLI TOOL DATA STORAGE                  │
+     └─────────────────────────────────────────────────┘
+
+     Key constraints:
+     • No daemon running
+     • Must work offline
+     • Single user
+
+                  SQLite          Postgres
+     Deployment   embedded ✓      needs server ✗
+     Offline      yes ✓           no ✗
+     Single file  yes ✓           no ✗
+
+     SQLite. Not even close.
+
+     Unless... is there a sync component?
+```
+
+---
+
+## Ending Discovery
+
+There's no required ending. Discovery might:
+
+- **Flow into a proposal**: "Ready to start? I can create a change proposal."
+- **Result in artifact updates**: "Updated design.md with these decisions"
+- **Just provide clarity**: User has what they need, moves on
+- **Continue later**: "We can pick this up anytime"
+
+When it feels like things are crystallizing, you might summarize:
+
+```
+## What We Figured Out
+
+**The problem**: [crystallized understanding]
+
+**The approach**: [if one emerged]
+
+**Open questions**: [if any remain]
+
+**Next steps** (if ready):
+- Create a change proposal
+- Keep exploring: just keep talking
+```
+
+But this summary is optional. Sometimes the thinking IS the value.
+
+---
+
+## Guardrails
+
+- **Don't implement** - Never write code or implement features. Creating OpenSpec artifacts is fine, writing application code is not.
+- **Don't fake understanding** - If something is unclear, dig deeper
+- **Don't rush** - Discovery is thinking time, not task time
+- **Don't force structure** - Let patterns emerge naturally
+- **Don't auto-capture** - Offer to save insights, don't just do it
+- **Do visualize** - A good diagram is worth many paragraphs
+- **Do explore the codebase** - Ground discussions in reality
+- **Do question assumptions** - Including the user's and your own
diff --git a/.roo/skills/openspec-propose/SKILL.md b/.roo/skills/openspec-propose/SKILL.md
new file mode 100644
index 0000000000..4b7e204184
--- /dev/null
+++ b/.roo/skills/openspec-propose/SKILL.md
@@ -0,0 +1,110 @@
+---
+name: openspec-propose
+description: Propose a new change with all artifacts generated in one step. Use when the user wants to quickly describe what they want to build and get a complete proposal with design, specs, and tasks ready for implementation.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.3.1"
+---
+
+Propose a new change - create the change and generate all artifacts in one step.
+
+I'll create a change with artifacts:
+- proposal.md (what & why)
+- design.md (how)
+- tasks.md (implementation steps)
+
+When ready to implement, run /opsx:apply
+
+---
+
+**Input**: The user's request should include a change name (kebab-case) OR a description of what they want to build.
+
+**Steps**
+
+1. **If no clear input provided, ask what they want to build**
+
+   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+   > "What change do you want to work on? Describe what you want to build or fix."
+
+   From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
+
+   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
+
+2. **Create the change directory**
+   ```bash
+   openspec new change "<name>"
+   ```
+   This creates a scaffolded change at `openspec/changes/<name>/` with `.openspec.yaml`.
+
+3. **Get the artifact build order**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to get:
+   - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
+   - `artifacts`: list of all artifacts with their status and dependencies
+
+4. **Create artifacts in sequence until apply-ready**
+
+   Use the **TodoWrite tool** to track progress through the artifacts.
+
+   Loop through artifacts in dependency order (artifacts with no pending dependencies first):
+
+   a. **For each artifact that is `ready` (dependencies satisfied)**:
+      - Get instructions:
+        ```bash
+        openspec instructions <artifact-id> --change "<name>" --json
+        ```
+      - The instructions JSON includes:
+        - `context`: Project background (constraints for you - do NOT include in output)
+        - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
+        - `template`: The structure to use for your output file
+        - `instruction`: Schema-specific guidance for this artifact type
+        - `outputPath`: Where to write the artifact
+        - `dependencies`: Completed artifacts to read for context
+      - Read any completed dependency files for context
+      - Create the artifact file using `template` as the structure
+      - Apply `context` and `rules` as constraints - but do NOT copy them into the file
+      - Show brief progress: "Created <artifact-id>"
+
+   b. **Continue until all `applyRequires` artifacts are complete**
+      - After creating each artifact, re-run `openspec status --change "<name>" --json`
+      - Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array
+      - Stop when all `applyRequires` artifacts are done
+
+   c. **If an artifact requires user input** (unclear context):
+      - Use **AskUserQuestion tool** to clarify
+      - Then continue with creation
+
+5. **Show final status**
+   ```bash
+   openspec status --change "<name>"
+   ```
+
+**Output**
+
+After completing all artifacts, summarize:
+- Change name and location
+- List of artifacts created with brief descriptions
+- What's ready: "All artifacts created! Ready for implementation."
+- Prompt: "Run `/opsx:apply` or ask me to implement to start working on the tasks."
+
+**Artifact Creation Guidelines**
+
+- Follow the `instruction` field from `openspec instructions` for each artifact type
+- The schema defines what each artifact should contain - follow it
+- Read dependency artifacts for context before creating new ones
+- Use `template` as the structure for your output file - fill in its sections
+- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
+  - Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
+  - These guide what you write, but should never appear in the output
+
+**Guardrails**
+- Create ALL artifacts needed for implementation (as defined by schema's `apply.requires`)
+- Always read dependency artifacts before creating a new one
+- If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
+- If a change with that name already exists, ask if user wants to continue it or create a new one
+- Verify each artifact file exists after writing before proceeding to next
diff --git a/PROJECT_SUMMARY.md b/PROJECT_SUMMARY.md
new file mode 100644
index 0000000000..95fb3f61f7
--- /dev/null
+++ b/PROJECT_SUMMARY.md
@@ -0,0 +1,315 @@
+# WaveTerm — Project Overview
+
+> An open-source, AI-native terminal emulator for macOS, Linux, and Windows.
+> Built by Command Line Inc — https://waveterm.dev | License: Apache-2.0
+
+---
+
+## 1. Main Features
+
+- **Wave AI** — Context-aware terminal assistant. Reads terminal output, analyzes widgets, performs file operations. Supports OpenAI, Claude, Gemini, Azure, Perplexity, Ollama/LM Studio (local models). BYO-key model.
+- **Durable SSH Sessions** — Remote terminal sessions survive network interruptions and restarts with automatic reconnection.
+- **Flexible Drag-and-Drop Interface** — Organize terminal blocks, editors, web browsers, and AI assistants in a tiled layout.
+- **Built-in Editor** — Monaco-based code editor for editing remote files with syntax highlighting.
+- **Rich File Preview** — Preview markdown, images, video, PDFs, CSVs, directories on remote hosts.
+- **Command Blocks** — Isolate and monitor individual commands in dedicated blocks.
+- **`wsh` CLI** — Manage workspace from the command line and share data between terminal sessions.
+- **Secure Secret Storage** — Uses native system backends (Keychain, Credential Manager, etc.).
+- **No Accounts Required** — Telemetry-free, privacy-first.
+- **WaveApp Builder (Tsunami)** — Build custom UIs using a Go VDOM framework rendered in the terminal.
+
+---
+
+## 2. Tech Stack
+
+### Frontend (Renderer Process)
+| Technology        | Purpose                                    |
+|-------------------|--------------------------------------------|
+| React 19          | UI framework                               |
+| TypeScript 5.9    | Type-safe JavaScript                       |
+| Vite 6 + SWC      | Build tool & fast refresh                  |
+| Tailwind CSS v4   | Utility-first styling                      |
+| Jotai             | Atomic state management                    |
+| xterm.js          | Terminal emulator                          |
+| Monaco Editor     | Code editor                                |
+| Electron 41       | Desktop shell (main + renderer processes)  |
+| Floating UI       | Popovers & menus                           |
+| Recharts / Observable Plot | Charts & data visualization     |
+| Mermaid           | Diagram rendering                          |
+| Shiki             | Syntax highlighting                        |
+| React DnD         | Drag-and-drop                              |
+| Immer             | Immutable state updates                    |
+| Winston           | Logging                                    |
+| Vercel AI SDK     | Multi-provider AI integration              |
+
+### Backend (Go Server — `wavesrv`)
+| Technology               | Purpose                             |
+|--------------------------|-------------------------------------|
+| Go 1.25                  | Backend language                    |
+| gorilla/mux             | HTTP router                         |
+| gorilla/websocket       | WebSocket server (frontend comms)   |
+| go-sqlite3 + sqlx       | SQLite database                     |
+| golang-migrate/migrate  | DB migrations                       |
+| creack/pty (fork)       | PTY management                      |
+| crypto/ssh              | SSH client                          |
+| spf13/cobra             | CLI framework (wsh)                 |
+| shirou/gopsutil         | System/process monitoring           |
+| google/generative-ai-go | Gemini AI integration               |
+| golang-jwt/jwt          | JWT auth                            |
+| fsnotify                | File system watcher (config HMR)    |
+
+### Dev Tooling
+| Tool              | Purpose                          |
+|-------------------|----------------------------------|
+| Task (Taskfile)   | Build orchestrator (replaces Make) |
+| electron-vite     | Electron + Vite integration       |
+| electron-builder  | Packaging & distribution         |
+| Zig compiler      | CGO cross-compilation            |
+| ESLint + Prettier | JS/TS linting & formatting       |
+| golangci-lint     | Go linting                       |
+
+---
+
+## 3. Project Architecture
+
+```
+┌─────────────────────────────────────────────────────┐
+│                  Electron Main Process              │
+│                   (emain/emain.ts)                  │
+│  ┌──────────┐  ┌────────────┐  ┌────────────────┐  │
+│  │ App Mgmt │  │ Windows/   │  │ Spawns wavesrv │  │
+│  │ Lifecycle│  │ Menus      │  │ (Go backend)   │  │
+│  └──────────┘  └────────────┘  └───────┬────────┘  │
+│                                        │            │
+│  ┌──────────────────────────────────────┘            │
+│  │  Preload Script (emain/preload.ts)                │
+│  │  contextBridge → window.api (IPC)                │
+│  └──────────────────────────────────────────────────┘
+│                         │
+├─────────────────────────┼───────────────────────────┤
+│              Renderer Process                       │
+│  ┌──────────────────────────────────────────────────┐│
+│  │  React App (frontend/app/app.tsx)               ││
+│  │  ┌──────────┐ ┌──────────┐ ┌──────────────────┐ ││
+│  │  │Terminal  │ │  AI      │ │  Preview / Web   │ ││
+│  │  │Block     │ │  Panel   │ │  Block           │ ││
+│  │  └──────────┘ └──────────┘ └──────────────────┘ ││
+│  │  ┌──────────┐ ┌──────────┐ ┌──────────────────┐ ││
+│  │  │Monaco    │ │ Tsunami  │ │  Tab Bar, Menu,  │ ││
+│  │  │Editor    │ │ VDom     │ │  Modals, ...     │ ││
+│  │  └──────────┘ └──────────┘ └──────────────────┘ ││
+│  │                                                  ││
+│  │  State: Jotai atoms + WOS (Wave Object Store)   ││
+│  │  Comms: WPS (Wave PubSub) over WebSocket        ││
+│  └──────────────────────────────────────────────────┘│
+└──────────────────────────────────────────────────────┘
+                         │
+              WebSocket / WSH RPC
+                         │
+┌─────────────────────────────────────────────────────┐
+│              Go Backend (cmd/server/)               │
+│  ┌──────────┐ ┌──────────┐ ┌──────────────────────┐ │
+│  │WebSocket │ │  HTTP    │ │  WSH RPC Router     │ │
+│  │Server    │ │  Server  │ │  (wshrpc/)           │ │
+│  └──────────┘ └──────────┘ └──────────────────────┘ │
+│  ┌──────────┐ ┌──────────┐ ┌──────────────────────┐ │
+│  │Block Ctrl│ │ Job Ctrl │ │ SSH Conn Controller │ │
+│  └──────────┘ └──────────┘ └──────────────────────┘ │
+│  ┌──────────┐ ┌──────────┐ ┌──────────────────────┐ │
+│  │  AI      │ │ Database │ │  Config / Secret     │ │
+│  │  Service │ │ (SQLite) │ │  Store               │ │
+│  └──────────┘ └──────────┘ └──────────────────────┘ │
+│  ┌──────────┐ ┌──────────┐                          │
+│  │ Telemetry│ │ Tsunami  │                          │
+│  │          │ │ VDom     │                          │
+│  └──────────┘ └──────────┘                          │
+└─────────────────────────────────────────────────────┘
+```
+
+### Communication Flow
+- **Frontend ↔ Backend**: WSH RPC over WebSocket (or Unix domain socket)
+- **RPC definitions**: `pkg/wshrpc/wshrpctypes.go` (Go) → auto-generated TypeScript bindings in `frontend/types/`
+- **Event system**: WPS (Wave PubSub) for async event-driven communication
+- **State**: Wave Object Store (WOS) backed by SQLite, reactive via Jotai atoms
+
+### Key Directories
+| Directory          | Purpose                                    |
+|--------------------|--------------------------------------------|
+| `frontend/`        | TypeScript/React UI (renderer process)     |
+| `emain/`           | Electron main process                      |
+| `pkg/`             | Go backend library (47 sub-packages)       |
+| `cmd/`             | Go binary entry points (server, wsh, codegen) |
+| `tsunami/`         | WaveApp framework (separate Go module)     |
+| `db/`              | SQLite database setup & migrations         |
+| `schema/`          | JSON schemas for settings, connections, etc. |
+| `docs/`            | Docusaurus documentation site              |
+| `tests/`           | Integration tests                          |
+| `testdriver/`      | TestDriver.ai E2E test infrastructure      |
+| `build/`           | Platform-specific build resources          |
+| `public/`          | Static assets (fonts, icons)              |
+| `.github/workflows/` | CI/CD pipelines (9 workflows)          |
+
+---
+
+## 4. Development Setup
+
+### Prerequisites
+- Go 1.25+
+- Node.js 22 LTS
+- Task CLI (https://taskfile.dev)
+- Zig compiler (for CGO cross-compilation)
+
+### Quick Start
+```bash
+task init          # npm install + go mod tidy + docs setup
+task dev           # Full dev mode (HMR, builds backend)
+task preview       # Standalone preview server (no Electron, port 7007)
+npm run dev        # electron-vite dev (equivalent to above)
+```
+
+### Key Commands
+| Command              | Description                               |
+|----------------------|-------------------------------------------|
+| `task dev`           | Full dev mode with HMR                    |
+| `task start`         | Run built app standalone                  |
+| `task package`       | Production build + platform installer     |
+| `task build:backend` | Build wavesrv + wsh binaries              |
+| `task generate`      | Regenerate TypeScript bindings from Go    |
+| `task check:ts`      | TypeScript type checking (`tsc --noEmit`) |
+| `task clean`         | Remove dist/ and make/ directories        |
+| `task docsite`       | Start documentation dev server            |
+
+---
+
+## 5. Testing
+
+### Frontend (Vitest)
+```bash
+npm test              # Run all tests (vitest, single run)
+npm run coverage      # Run with Istanbul coverage (output: ./coverage/)
+npx vitest            # Run in watch mode
+```
+
+- **Framework**: Vitest v3 with Istanbul coverage
+- **Location**: Tests co-located with source as `*.test.ts` / `*.test.tsx`
+- **Pattern**: Pure logic tests use `describe`/`it`; component tests use `renderToStaticMarkup`; API mocking via `vi.mock()`
+- **TypeCheck**: Vitest also runs TypeScript typechecking during tests
+- **Output**: JUnit XML to `test-results.xml`, LCOV coverage to `./coverage/`
+
+**Test files (frontend):** ~14 files covering layout algorithms, tree views, widgets, context menus, WebView, terminal OSC handlers, color validation, etc.
+
+### Backend (Go)
+```bash
+go test ./...                        # All Go tests
+go test -v ./pkg/util/fileutil/...   # Specific package, verbose
+```
+
+- **Framework**: Standard Go `testing` package (no testify/ginkgo)
+- **Location**: Tests co-located as `*_test.go` (white-box, same package)
+- **Pattern**: `t *testing.T`, `t.TempDir()`, hand-written mock structs
+- **Coverage**: No Go coverage configured in CI
+
+**Test files (Go):** ~30 test files covering file utilities, AI chat, SSH, streams, data structures, DOM rendering, etc.
+
+### E2E / Integration
+- **TestDriver.ai** — AI-driven visual/E2E tests, run in CI on Windows
+- **CI**: GitHub Actions — 9 workflows (build, testdriver, codeql, merge gatekeeper)
+
+### Linting & Formatting
+```bash
+# TypeScript/React
+npx eslint frontend/ emain/          # ESLint 9 flat config
+npx prettier --check .               # Prettier formatting
+
+# Go
+golangci-lint run                    # golangci-lint (minimal config)
+```
+
+> **Note**: Unit tests are NOT run in CI — they are expected to be executed locally. CI only runs TestDriver.ai E2E tests, CodeQL analysis, and build validation.
+
+---
+
+## 6. Debugging
+
+### Dev Mode
+```bash
+task dev            # Full dev mode: Vite HMR + Go backend + Electron
+```
+- **Frontend HMR**: Hot Module Replacement via Vite (React components update instantly)
+- **Go Backend**: Spawned as a child process by Electron, restarted on changes
+- **Chrome DevTools**: `Cmd+Option+I` (macOS) / `Ctrl+Shift+I` (Windows/Linux) in the running app
+
+### Logging
+| Log Source        | Location / Method                                |
+|-------------------|--------------------------------------------------|
+| Electron (main)   | `{dataDir}/waveapp.log` (winston, rotated at 10MB) |
+| Go backend        | stderr → captured by Electron → waveapp.log      |
+| Frontend debug    | `debug("wave:workspace")` etc. (npm `debug` package) |
+| Block debug       | `pkg/blocklogger` — writes logs to terminal block UI |
+| Dev-only          | `logutil.DevPrintf()` — only in dev mode          |
+
+### Data & Config Directories
+- **Dev mode**: `~/.waveterm-dev/`
+- **Production**: Platform-specific (`~/Library/Application Support/waveterm/`, `~/.config/waveterm/`, `%LOCALAPPDATA%/waveterm/`)
+
+### Debug Tools
+- **pprof**: Enable via `debug:pprofport` setting in config
+- **Connection debug**: Set block meta `term:conndebug` to `"info"` or `"debug"`
+- **WebGL debug**: Set `debug:webglstatus` config key
+- **SIGUSR1 dump** (Unix): Dumps debug info to `/tmp/waveterm-usr1-dump.log`
+- **VS Code**: No `launch.json` provided; recommended extensions: Prettier, Go, ESLint, Vitest, Task
+
+### Environment Variables
+| Variable                 | Purpose                            |
+|--------------------------|------------------------------------|
+| `WAVETERM_DEV`           | Marks dev mode (auto-set by Electron) |
+| `WAVETERM_ENVFILE`       | Path to `.env` file                |
+| `WAVETERM_CONFIG_HOME`   | Config directory override          |
+| `WAVETERM_DATA_HOME`     | Data directory override            |
+| `WAVETERM_NOCONFIRMQUIT` | Skip quit confirmation (dev mode)  |
+| `WCLOUD_ENDPOINT`        | Cloud API endpoint (dev/staging)   |
+
+---
+
+## 7. Build & Deploy
+
+### Production Build
+```bash
+task package          # Full production build + platform installer
+```
+
+- **Go cross-compilation**: Uses Zig compiler for fully static CGO binaries
+- **Targets**: macOS (arm64/amd64), Linux (arm64/amd64), Windows (arm64/amd64), plus MIPS/MIPS64 for wsh
+- **Electron packaging**: electron-builder — creates DMG/zip (macOS), NSIS/MSI/zip (Windows), deb/rpm/snap/AppImage/pacman (Linux)
+- **App ID**: `dev.commandline.waveterm`
+
+### Code Generation
+```bash
+task generate         # Generates:
+                      # - frontend/types/gotypes.d.ts (TS from Go types)
+                      # - Go server stubs from RPC definitions
+                      # - JSON schemas from Go config types
+```
+
+### CI/CD (GitHub Actions)
+- 9 workflow files in `.github/workflows/`
+- Build validation on PR (wavesrv + wsh + frontend)
+- TestDriver.ai E2E tests (Windows)
+- CodeQL static analysis
+- Merge gatekeeper (requires: Build, TestDriver, CodeQL, License Compliance, CodeRabbit)
+
+---
+
+## 8. Key Conventions
+
+- **Go**: String constants over custom enums, `Printf` over `Println`, `Make` over `New`, `defer lock.Unlock()`
+- **TypeScript**: Named exports only, 4-space indent, `@/` path aliases, `cn()` for class merging
+- **Styling**: Tailwind v4; custom CSS in `frontend/tailwindsetup.css`
+- **State**: Jotai atoms; singleton models with `getInstance()`, `private constructor`
+- **RPC**: Define in `pkg/wshrpc/wshrpctypes.go`, implement in `pkg/wshrpc/wshserver.go`, run `task generate`
+- **All lowercase** filenames and JSON fields
+- **No Makefile** — use `Task` (Taskfile.yml)
+
+---
+
+*Generated from project exploration — May 2026*
diff --git a/frontend/app/view/term/termwrap.ts b/frontend/app/view/term/termwrap.ts
index d10b600459..4840b5d914 100644
--- a/frontend/app/view/term/termwrap.ts
+++ b/frontend/app/view/term/termwrap.ts
@@ -389,10 +389,9 @@ export class TermWrap {
                     if (!globalStore.get(copyOnSelectAtom)) {
                         return;
                     }
-                    // Don't copy-on-select when the search bar has focus — navigating
+                    // Don't copy-on-select when the search bar is open — navigating
                     // search results changes the terminal selection programmatically.
-                    const active = document.activeElement;
-                    if (active != null && active.closest(".search-container") != null) {
+                    if (document.querySelector(".search-container") != null) {
                         return;
                     }
                     let selectedText = this.terminal.getSelection();
diff --git a/frontend/types/gotypes.d.ts b/frontend/types/gotypes.d.ts
index c5b870d7ed..b3220ab6d1 100644
--- a/frontend/types/gotypes.d.ts
+++ b/frontend/types/gotypes.d.ts
@@ -1589,6 +1589,7 @@ declare global {
         "debug:panictype"?: string;
         "block:view"?: string;
         "block:controller"?: string;
+        "block:subblock"?: boolean;
         "ai:backendtype"?: string;
         "ai:local"?: boolean;
         "wsh:cmd"?: string;
diff --git a/go.mod b/go.mod
index 460763ba8f..2165fda9dc 100644
--- a/go.mod
+++ b/go.mod
@@ -60,6 +60,7 @@ require (
 	github.com/lufia/plan9stats v0.0.0-20211012122336-39d0f177ccd0 // indirect
 	github.com/mailru/easyjson v0.7.7 // indirect
 	github.com/mattn/go-isatty v0.0.20 // indirect
+	github.com/outrigdev/goid v0.3.0 // indirect
 	github.com/power-devops/perfstat v0.0.0-20240221224432-82ca36839d55 // indirect
 	github.com/rivo/uniseg v0.4.7 // indirect
 	github.com/sirupsen/logrus v1.9.3 // indirect
diff --git a/go.sum b/go.sum
index 139b34b195..41ae6f4cda 100644
--- a/go.sum
+++ b/go.sum
@@ -108,6 +108,8 @@ github.com/mattn/go-sqlite3 v1.14.40 h1:f7+saIsbq4EF86mUqe0uiecQOJYMOdfi5uATADmU
 github.com/mattn/go-sqlite3 v1.14.40/go.mod h1:pjEuOr8IwzLJP2MfGeTb0A35jauH+C2kbHKBr7yXKVQ=
 github.com/mitchellh/mapstructure v1.5.0 h1:jeMsZIYE/09sWLaz43PL7Gy6RuMjD2eJVyuac5Z2hdY=
 github.com/mitchellh/mapstructure v1.5.0/go.mod h1:bFUtVrKA4DC2yAKiSyO/QUcy7e+RRV2QTWOzhPopBRo=
+github.com/outrigdev/goid v0.3.0 h1:t/otQD3EXc45cLtQVPUnNgEyRaTQA4cPeu3qVcrsIws=
+github.com/outrigdev/goid v0.3.0/go.mod h1:hEH7f27ypN/GHWt/7gvkRoFYR0LZizfUBIAbak4neVE=
 github.com/photostorm/pty v1.1.19-0.20230903182454-31354506054b h1:cLGKfKb1uk0hxI0Q8L83UAJPpeJ+gSpn3cCU/tjd3eg=
 github.com/photostorm/pty v1.1.19-0.20230903182454-31354506054b/go.mod h1:KO+FcPtyLAiRC0hJwreJVvfwc7vnNz77UxBTIGHdPVk=
 github.com/planetscale/vtprotobuf v0.6.1-0.20240319094008-0393e58bdf10 h1:GFCKgmp0tecUJ0sJuv4pzYCqS9+RGSn52M3FUwPs+uo=
diff --git a/openspec/changes/archive/2026-05-30-fix-search-copyonselect-clipboard/.openspec.yaml b/openspec/changes/archive/2026-05-30-fix-search-copyonselect-clipboard/.openspec.yaml
new file mode 100644
index 0000000000..b44fb0ec50
--- /dev/null
+++ b/openspec/changes/archive/2026-05-30-fix-search-copyonselect-clipboard/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-05-30
diff --git a/openspec/changes/archive/2026-05-30-fix-search-copyonselect-clipboard/design.md b/openspec/changes/archive/2026-05-30-fix-search-copyonselect-clipboard/design.md
new file mode 100644
index 0000000000..46175f8953
--- /dev/null
+++ b/openspec/changes/archive/2026-05-30-fix-search-copyonselect-clipboard/design.md
@@ -0,0 +1,47 @@
+## Context
+
+The `copy-on-select` feature in `termwrap.ts` listens to `terminal.onSelectionChange` and writes terminal selection to clipboard. When search is open, navigating results programmatically triggers selection changes. The current guard only checks if `document.activeElement` is within `.search-container` — but when focus is on the terminal (user clicks terminal after searching), this guard passes and clipboard gets overwritten.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Prevent copy-on-select from firing when search navigation causes terminal selection changes
+- Preserve copy-on-select behavior for manual user selections (mouse drag) even when search is open
+
+**Non-Goals:**
+- No changes to the search component itself
+- No new settings or configuration options
+
+## Decisions
+
+**Decision: Check search open state via DOM query instead of atom**
+
+The simplest and most reliable approach is to check if `.search-container` exists in the DOM when `onSelectionChange` fires. If the search container element is present, the selection change is likely from search navigation, not user action.
+
+- Alternative considered: Using a Jotai atom to track search open state — more complex, requires cross-component wiring
+- Alternative considered: Adding a flag that search sets before/after navigation — fragile, harder to maintain
+
+The DOM query approach (`document.querySelector('.search-container')`) is:
+- Zero additional state management
+- Automatically in sync with the UI
+- No new props or atoms needed
+- Minimal performance impact (one DOM query per selection change, debounced at 50ms)
+
+**Decision: Broaden the existing guard**
+
+Current code (line 394-396):
+```ts
+const active = document.activeElement;
+if (active != null && active.closest(".search-container") != null) { return; }
+```
+
+Replace with:
+```ts
+if (document.querySelector(".search-container") != null) { return; }
+```
+
+This catches all cases: whether focus is on search, terminal, or anywhere else.
+
+## Risks / Trade-offs
+
+- **[False positive]**: If user manually selects terminal text while search is open, copy-on-select will NOT fire. This is an acceptable trade-off — the user can still use Ctrl+Shift+C to copy. The search-open state implies the user is in "search mode", not "copy mode".
diff --git a/openspec/changes/archive/2026-05-30-fix-search-copyonselect-clipboard/proposal.md b/openspec/changes/archive/2026-05-30-fix-search-copyonselect-clipboard/proposal.md
new file mode 100644
index 0000000000..3dee916ca7
--- /dev/null
+++ b/openspec/changes/archive/2026-05-30-fix-search-copyonselect-clipboard/proposal.md
@@ -0,0 +1,23 @@
+## Why
+
+When search is open with results, navigating through search results programmatically changes the terminal selection. If `term:copyonselect` is enabled, this triggers `navigator.clipboard.writeText()` which overwrites the user's clipboard content without their knowledge. Users lose clipboard data when they navigate search results, causing confusion and data loss.
+
+## What Changes
+
+- Add a guard in the copy-on-select handler to skip clipboard writes when the search bar is open (not just when it has focus)
+- The existing guard only checks if `document.activeElement` is within `.search-container`, which allows clipboard overwrites when search is open but focus is on the terminal
+
+## Capabilities
+
+### New Capabilities
+
+- `search-clipboard-guard`: Prevent copy-on-select from overwriting clipboard when search is actively open, regardless of focus state
+
+### Modified Capabilities
+
+- `<existing-name>`: no spec-level requirement changes — this is a behavioral fix to existing implementation
+
+## Impact
+
+- `frontend/app/view/term/termwrap.ts:386-407` — copy-on-select onSelectionChange handler
+- No API changes, no dependency changes
diff --git a/openspec/changes/archive/2026-05-30-fix-search-copyonselect-clipboard/specs/search-clipboard-guard/spec.md b/openspec/changes/archive/2026-05-30-fix-search-copyonselect-clipboard/specs/search-clipboard-guard/spec.md
new file mode 100644
index 0000000000..3cf347bee5
--- /dev/null
+++ b/openspec/changes/archive/2026-05-30-fix-search-copyonselect-clipboard/specs/search-clipboard-guard/spec.md
@@ -0,0 +1,15 @@
+## ADDED Requirements
+
+### Requirement: Prevent clipboard overwrite when search is open
+
+When search is active and `term:copyonselect` is enabled, navigating search results MUST NOT trigger clipboard writes.
+
+#### Scenario: Search navigation does not overwrite clipboard
+- **WHEN** search bar is open with results
+- **WHEN** user navigates through search results (Enter/Prev/Next)
+- **THEN** `navigator.clipboard.writeText()` MUST NOT be called for the programmatic selection change
+
+#### Scenario: Manual terminal selection still copies on select
+- **WHEN** search bar is open
+- **WHEN** user manually selects text in the terminal (via mouse drag)
+- **THEN** copy-on-select SHOULD still copy the selected text to clipboard
diff --git a/openspec/changes/archive/2026-05-30-fix-search-copyonselect-clipboard/tasks.md b/openspec/changes/archive/2026-05-30-fix-search-copyonselect-clipboard/tasks.md
new file mode 100644
index 0000000000..c88067ed31
--- /dev/null
+++ b/openspec/changes/archive/2026-05-30-fix-search-copyonselect-clipboard/tasks.md
@@ -0,0 +1,10 @@
+## 1. Guard Implementation
+
+- [x] 1.1 Modify copy-on-select guard in `termwrap.ts` to check for `.search-container` DOM presence instead of only checking `document.activeElement`
+- [x] 1.2 Verify the fix works in all scenarios: search open + terminal focus, search closed, search open + search focus
+
+## 2. Verification
+
+- [x] 2.1 Manual test: enable `term:copyonselect`, open search, navigate results, verify clipboard is NOT overwritten
+- [x] 2.2 Manual test: with search open, manually select terminal text, verify copy-on-select does NOT fire (acceptable trade-off per design)
+- [x] 2.3 Manual test: close search, manually select terminal text, verify copy-on-select still works
diff --git a/openspec/specs/search-clipboard-guard/spec.md b/openspec/specs/search-clipboard-guard/spec.md
new file mode 100644
index 0000000000..3cf347bee5
--- /dev/null
+++ b/openspec/specs/search-clipboard-guard/spec.md
@@ -0,0 +1,15 @@
+## ADDED Requirements
+
+### Requirement: Prevent clipboard overwrite when search is open
+
+When search is active and `term:copyonselect` is enabled, navigating search results MUST NOT trigger clipboard writes.
+
+#### Scenario: Search navigation does not overwrite clipboard
+- **WHEN** search bar is open with results
+- **WHEN** user navigates through search results (Enter/Prev/Next)
+- **THEN** `navigator.clipboard.writeText()` MUST NOT be called for the programmatic selection change
+
+#### Scenario: Manual terminal selection still copies on select
+- **WHEN** search bar is open
+- **WHEN** user manually selects text in the terminal (via mouse drag)
+- **THEN** copy-on-select SHOULD still copy the selected text to clipboard
diff --git a/package-lock.json b/package-lock.json
index d3167a5ac5..fdf8623be7 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -76,7 +76,7 @@
                 "throttle-debounce": "^5.0.2",
                 "unist-util-visit": "^5.1.0",
                 "use-device-pixel-ratio": "^1.1.2",
-                "uuid": "^14.0.0",
+                "uuid": "14.0.0",
                 "winston": "^3.19.0",
                 "ws": "^8.19.0",
                 "yaml": "^2.8.3"
@@ -4848,18 +4848,6 @@
                 "node": ">=14.14"
             }
         },
-        "node_modules/@emnapi/runtime": {
-            "version": "1.5.0",
-            "resolved": "https://registry.npmjs.org/@emnapi/runtime/-/runtime-1.5.0.tgz",
-            "integrity": "sha512-97/BJ3iXHww3djw6hYIfErCZFee7qCtrneuLa20UXFCOTCfBM2cvQHjWJ2EG0s0MtdNwInarqCTz35i4wWXHsQ==",
-            "dev": true,
-            "license": "MIT",
-            "optional": true,
-            "peer": true,
-            "dependencies": {
-                "tslib": "^2.4.0"
-            }
-        },
         "node_modules/@esbuild/aix-ppc64": {
             "version": "0.25.12",
             "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.25.12.tgz",
@@ -5576,468 +5564,6 @@
                 "url": "https://github.com/sponsors/sindresorhus"
             }
         },
-        "node_modules/@img/sharp-darwin-arm64": {
-            "version": "0.34.3",
-            "resolved": "https://registry.npmjs.org/@img/sharp-darwin-arm64/-/sharp-darwin-arm64-0.34.3.tgz",
-            "integrity": "sha512-ryFMfvxxpQRsgZJqBd4wsttYQbCxsJksrv9Lw/v798JcQ8+w84mBWuXwl+TT0WJ/WrYOLaYpwQXi3sA9nTIaIg==",
-            "cpu": [
-                "arm64"
-            ],
-            "dev": true,
-            "license": "Apache-2.0",
-            "optional": true,
-            "os": [
-                "darwin"
-            ],
-            "peer": true,
-            "engines": {
-                "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
-            },
-            "funding": {
-                "url": "https://opencollective.com/libvips"
-            },
-            "optionalDependencies": {
-                "@img/sharp-libvips-darwin-arm64": "1.2.0"
-            }
-        },
-        "node_modules/@img/sharp-darwin-x64": {
-            "version": "0.34.3",
-            "resolved": "https://registry.npmjs.org/@img/sharp-darwin-x64/-/sharp-darwin-x64-0.34.3.tgz",
-            "integrity": "sha512-yHpJYynROAj12TA6qil58hmPmAwxKKC7reUqtGLzsOHfP7/rniNGTL8tjWX6L3CTV4+5P4ypcS7Pp+7OB+8ihA==",
-            "cpu": [
-                "x64"
-            ],
-            "dev": true,
-            "license": "Apache-2.0",
-            "optional": true,
-            "os": [
-                "darwin"
-            ],
-            "peer": true,
-            "engines": {
-                "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
-            },
-            "funding": {
-                "url": "https://opencollective.com/libvips"
-            },
-            "optionalDependencies": {
-                "@img/sharp-libvips-darwin-x64": "1.2.0"
-            }
-        },
-        "node_modules/@img/sharp-libvips-darwin-arm64": {
-            "version": "1.2.0",
-            "resolved": "https://registry.npmjs.org/@img/sharp-libvips-darwin-arm64/-/sharp-libvips-darwin-arm64-1.2.0.tgz",
-            "integrity": "sha512-sBZmpwmxqwlqG9ueWFXtockhsxefaV6O84BMOrhtg/YqbTaRdqDE7hxraVE3y6gVM4eExmfzW4a8el9ArLeEiQ==",
-            "cpu": [
-                "arm64"
-            ],
-            "dev": true,
-            "license": "LGPL-3.0-or-later",
-            "optional": true,
-            "os": [
-                "darwin"
-            ],
-            "peer": true,
-            "funding": {
-                "url": "https://opencollective.com/libvips"
-            }
-        },
-        "node_modules/@img/sharp-libvips-darwin-x64": {
-            "version": "1.2.0",
-            "resolved": "https://registry.npmjs.org/@img/sharp-libvips-darwin-x64/-/sharp-libvips-darwin-x64-1.2.0.tgz",
-            "integrity": "sha512-M64XVuL94OgiNHa5/m2YvEQI5q2cl9d/wk0qFTDVXcYzi43lxuiFTftMR1tOnFQovVXNZJ5TURSDK2pNe9Yzqg==",
-            "cpu": [
-                "x64"
-            ],
-            "dev": true,
-            "license": "LGPL-3.0-or-later",
-            "optional": true,
-            "os": [
-                "darwin"
-            ],
-            "peer": true,
-            "funding": {
-                "url": "https://opencollective.com/libvips"
-            }
-        },
-        "node_modules/@img/sharp-libvips-linux-arm": {
-            "version": "1.2.0",
-            "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-arm/-/sharp-libvips-linux-arm-1.2.0.tgz",
-            "integrity": "sha512-mWd2uWvDtL/nvIzThLq3fr2nnGfyr/XMXlq8ZJ9WMR6PXijHlC3ksp0IpuhK6bougvQrchUAfzRLnbsen0Cqvw==",
-            "cpu": [
-                "arm"
-            ],
-            "dev": true,
-            "license": "LGPL-3.0-or-later",
-            "optional": true,
-            "os": [
-                "linux"
-            ],
-            "peer": true,
-            "funding": {
-                "url": "https://opencollective.com/libvips"
-            }
-        },
-        "node_modules/@img/sharp-libvips-linux-arm64": {
-            "version": "1.2.0",
-            "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-arm64/-/sharp-libvips-linux-arm64-1.2.0.tgz",
-            "integrity": "sha512-RXwd0CgG+uPRX5YYrkzKyalt2OJYRiJQ8ED/fi1tq9WQW2jsQIn0tqrlR5l5dr/rjqq6AHAxURhj2DVjyQWSOA==",
-            "cpu": [
-                "arm64"
-            ],
-            "dev": true,
-            "license": "LGPL-3.0-or-later",
-            "optional": true,
-            "os": [
-                "linux"
-            ],
-            "peer": true,
-            "funding": {
-                "url": "https://opencollective.com/libvips"
-            }
-        },
-        "node_modules/@img/sharp-libvips-linux-ppc64": {
-            "version": "1.2.0",
-            "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-ppc64/-/sharp-libvips-linux-ppc64-1.2.0.tgz",
-            "integrity": "sha512-Xod/7KaDDHkYu2phxxfeEPXfVXFKx70EAFZ0qyUdOjCcxbjqyJOEUpDe6RIyaunGxT34Anf9ue/wuWOqBW2WcQ==",
-            "cpu": [
-                "ppc64"
-            ],
-            "dev": true,
-            "license": "LGPL-3.0-or-later",
-            "optional": true,
-            "os": [
-                "linux"
-            ],
-            "peer": true,
-            "funding": {
-                "url": "https://opencollective.com/libvips"
-            }
-        },
-        "node_modules/@img/sharp-libvips-linux-s390x": {
-            "version": "1.2.0",
-            "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-s390x/-/sharp-libvips-linux-s390x-1.2.0.tgz",
-            "integrity": "sha512-eMKfzDxLGT8mnmPJTNMcjfO33fLiTDsrMlUVcp6b96ETbnJmd4uvZxVJSKPQfS+odwfVaGifhsB07J1LynFehw==",
-            "cpu": [
-                "s390x"
-            ],
-            "dev": true,
-            "license": "LGPL-3.0-or-later",
-            "optional": true,
-            "os": [
-                "linux"
-            ],
-            "peer": true,
-            "funding": {
-                "url": "https://opencollective.com/libvips"
-            }
-        },
-        "node_modules/@img/sharp-libvips-linux-x64": {
-            "version": "1.2.0",
-            "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-x64/-/sharp-libvips-linux-x64-1.2.0.tgz",
-            "integrity": "sha512-ZW3FPWIc7K1sH9E3nxIGB3y3dZkpJlMnkk7z5tu1nSkBoCgw2nSRTFHI5pB/3CQaJM0pdzMF3paf9ckKMSE9Tg==",
-            "cpu": [
-                "x64"
-            ],
-            "dev": true,
-            "license": "LGPL-3.0-or-later",
-            "optional": true,
-            "os": [
-                "linux"
-            ],
-            "peer": true,
-            "funding": {
-                "url": "https://opencollective.com/libvips"
-            }
-        },
-        "node_modules/@img/sharp-libvips-linuxmusl-arm64": {
-            "version": "1.2.0",
-            "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linuxmusl-arm64/-/sharp-libvips-linuxmusl-arm64-1.2.0.tgz",
-            "integrity": "sha512-UG+LqQJbf5VJ8NWJ5Z3tdIe/HXjuIdo4JeVNADXBFuG7z9zjoegpzzGIyV5zQKi4zaJjnAd2+g2nna8TZvuW9Q==",
-            "cpu": [
-                "arm64"
-            ],
-            "dev": true,
-            "license": "LGPL-3.0-or-later",
-            "optional": true,
-            "os": [
-                "linux"
-            ],
-            "peer": true,
-            "funding": {
-                "url": "https://opencollective.com/libvips"
-            }
-        },
-        "node_modules/@img/sharp-libvips-linuxmusl-x64": {
-            "version": "1.2.0",
-            "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linuxmusl-x64/-/sharp-libvips-linuxmusl-x64-1.2.0.tgz",
-            "integrity": "sha512-SRYOLR7CXPgNze8akZwjoGBoN1ThNZoqpOgfnOxmWsklTGVfJiGJoC/Lod7aNMGA1jSsKWM1+HRX43OP6p9+6Q==",
-            "cpu": [
-                "x64"
-            ],
-            "dev": true,
-            "license": "LGPL-3.0-or-later",
-            "optional": true,
-            "os": [
-                "linux"
-            ],
-            "peer": true,
-            "funding": {
-                "url": "https://opencollective.com/libvips"
-            }
-        },
-        "node_modules/@img/sharp-linux-arm": {
-            "version": "0.34.3",
-            "resolved": "https://registry.npmjs.org/@img/sharp-linux-arm/-/sharp-linux-arm-0.34.3.tgz",
-            "integrity": "sha512-oBK9l+h6KBN0i3dC8rYntLiVfW8D8wH+NPNT3O/WBHeW0OQWCjfWksLUaPidsrDKpJgXp3G3/hkmhptAW0I3+A==",
-            "cpu": [
-                "arm"
-            ],
-            "dev": true,
-            "license": "Apache-2.0",
-            "optional": true,
-            "os": [
-                "linux"
-            ],
-            "peer": true,
-            "engines": {
-                "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
-            },
-            "funding": {
-                "url": "https://opencollective.com/libvips"
-            },
-            "optionalDependencies": {
-                "@img/sharp-libvips-linux-arm": "1.2.0"
-            }
-        },
-        "node_modules/@img/sharp-linux-arm64": {
-            "version": "0.34.3",
-            "resolved": "https://registry.npmjs.org/@img/sharp-linux-arm64/-/sharp-linux-arm64-0.34.3.tgz",
-            "integrity": "sha512-QdrKe3EvQrqwkDrtuTIjI0bu6YEJHTgEeqdzI3uWJOH6G1O8Nl1iEeVYRGdj1h5I21CqxSvQp1Yv7xeU3ZewbA==",
-            "cpu": [
-                "arm64"
-            ],
-            "dev": true,
-            "license": "Apache-2.0",
-            "optional": true,
-            "os": [
-                "linux"
-            ],
-            "peer": true,
-            "engines": {
-                "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
-            },
-            "funding": {
-                "url": "https://opencollective.com/libvips"
-            },
-            "optionalDependencies": {
-                "@img/sharp-libvips-linux-arm64": "1.2.0"
-            }
-        },
-        "node_modules/@img/sharp-linux-ppc64": {
-            "version": "0.34.3",
-            "resolved": "https://registry.npmjs.org/@img/sharp-linux-ppc64/-/sharp-linux-ppc64-0.34.3.tgz",
-            "integrity": "sha512-GLtbLQMCNC5nxuImPR2+RgrviwKwVql28FWZIW1zWruy6zLgA5/x2ZXk3mxj58X/tszVF69KK0Is83V8YgWhLA==",
-            "cpu": [
-                "ppc64"
-            ],
-            "dev": true,
-            "license": "Apache-2.0",
-            "optional": true,
-            "os": [
-                "linux"
-            ],
-            "peer": true,
-            "engines": {
-                "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
-            },
-            "funding": {
-                "url": "https://opencollective.com/libvips"
-            },
-            "optionalDependencies": {
-                "@img/sharp-libvips-linux-ppc64": "1.2.0"
-            }
-        },
-        "node_modules/@img/sharp-linux-s390x": {
-            "version": "0.34.3",
-            "resolved": "https://registry.npmjs.org/@img/sharp-linux-s390x/-/sharp-linux-s390x-0.34.3.tgz",
-            "integrity": "sha512-3gahT+A6c4cdc2edhsLHmIOXMb17ltffJlxR0aC2VPZfwKoTGZec6u5GrFgdR7ciJSsHT27BD3TIuGcuRT0KmQ==",
-            "cpu": [
-                "s390x"
-            ],
-            "dev": true,
-            "license": "Apache-2.0",
-            "optional": true,
-            "os": [
-                "linux"
-            ],
-            "peer": true,
-            "engines": {
-                "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
-            },
-            "funding": {
-                "url": "https://opencollective.com/libvips"
-            },
-            "optionalDependencies": {
-                "@img/sharp-libvips-linux-s390x": "1.2.0"
-            }
-        },
-        "node_modules/@img/sharp-linux-x64": {
-            "version": "0.34.3",
-            "resolved": "https://registry.npmjs.org/@img/sharp-linux-x64/-/sharp-linux-x64-0.34.3.tgz",
-            "integrity": "sha512-8kYso8d806ypnSq3/Ly0QEw90V5ZoHh10yH0HnrzOCr6DKAPI6QVHvwleqMkVQ0m+fc7EH8ah0BB0QPuWY6zJQ==",
-            "cpu": [
-                "x64"
-            ],
-            "dev": true,
-            "license": "Apache-2.0",
-            "optional": true,
-            "os": [
-                "linux"
-            ],
-            "peer": true,
-            "engines": {
-                "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
-            },
-            "funding": {
-                "url": "https://opencollective.com/libvips"
-            },
-            "optionalDependencies": {
-                "@img/sharp-libvips-linux-x64": "1.2.0"
-            }
-        },
-        "node_modules/@img/sharp-linuxmusl-arm64": {
-            "version": "0.34.3",
-            "resolved": "https://registry.npmjs.org/@img/sharp-linuxmusl-arm64/-/sharp-linuxmusl-arm64-0.34.3.tgz",
-            "integrity": "sha512-vAjbHDlr4izEiXM1OTggpCcPg9tn4YriK5vAjowJsHwdBIdx0fYRsURkxLG2RLm9gyBq66gwtWI8Gx0/ov+JKQ==",
-            "cpu": [
-                "arm64"
-            ],
-            "dev": true,
-            "license": "Apache-2.0",
-            "optional": true,
-            "os": [
-                "linux"
-            ],
-            "peer": true,
-            "engines": {
-                "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
-            },
-            "funding": {
-                "url": "https://opencollective.com/libvips"
-            },
-            "optionalDependencies": {
-                "@img/sharp-libvips-linuxmusl-arm64": "1.2.0"
-            }
-        },
-        "node_modules/@img/sharp-linuxmusl-x64": {
-            "version": "0.34.3",
-            "resolved": "https://registry.npmjs.org/@img/sharp-linuxmusl-x64/-/sharp-linuxmusl-x64-0.34.3.tgz",
-            "integrity": "sha512-gCWUn9547K5bwvOn9l5XGAEjVTTRji4aPTqLzGXHvIr6bIDZKNTA34seMPgM0WmSf+RYBH411VavCejp3PkOeQ==",
-            "cpu": [
-                "x64"
-            ],
-            "dev": true,
-            "license": "Apache-2.0",
-            "optional": true,
-            "os": [
-                "linux"
-            ],
-            "peer": true,
-            "engines": {
-                "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
-            },
-            "funding": {
-                "url": "https://opencollective.com/libvips"
-            },
-            "optionalDependencies": {
-                "@img/sharp-libvips-linuxmusl-x64": "1.2.0"
-            }
-        },
-        "node_modules/@img/sharp-wasm32": {
-            "version": "0.34.3",
-            "resolved": "https://registry.npmjs.org/@img/sharp-wasm32/-/sharp-wasm32-0.34.3.tgz",
-            "integrity": "sha512-+CyRcpagHMGteySaWos8IbnXcHgfDn7pO2fiC2slJxvNq9gDipYBN42/RagzctVRKgxATmfqOSulgZv5e1RdMg==",
-            "cpu": [
-                "wasm32"
-            ],
-            "dev": true,
-            "license": "Apache-2.0 AND LGPL-3.0-or-later AND MIT",
-            "optional": true,
-            "peer": true,
-            "dependencies": {
-                "@emnapi/runtime": "^1.4.4"
-            },
-            "engines": {
-                "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
-            },
-            "funding": {
-                "url": "https://opencollective.com/libvips"
-            }
-        },
-        "node_modules/@img/sharp-win32-arm64": {
-            "version": "0.34.3",
-            "resolved": "https://registry.npmjs.org/@img/sharp-win32-arm64/-/sharp-win32-arm64-0.34.3.tgz",
-            "integrity": "sha512-MjnHPnbqMXNC2UgeLJtX4XqoVHHlZNd+nPt1kRPmj63wURegwBhZlApELdtxM2OIZDRv/DFtLcNhVbd1z8GYXQ==",
-            "cpu": [
-                "arm64"
-            ],
-            "dev": true,
-            "license": "Apache-2.0 AND LGPL-3.0-or-later",
-            "optional": true,
-            "os": [
-                "win32"
-            ],
-            "peer": true,
-            "engines": {
-                "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
-            },
-            "funding": {
-                "url": "https://opencollective.com/libvips"
-            }
-        },
-        "node_modules/@img/sharp-win32-ia32": {
-            "version": "0.34.3",
-            "resolved": "https://registry.npmjs.org/@img/sharp-win32-ia32/-/sharp-win32-ia32-0.34.3.tgz",
-            "integrity": "sha512-xuCdhH44WxuXgOM714hn4amodJMZl3OEvf0GVTm0BEyMeA2to+8HEdRPShH0SLYptJY1uBw+SCFP9WVQi1Q/cw==",
-            "cpu": [
-                "ia32"
-            ],
-            "dev": true,
-            "license": "Apache-2.0 AND LGPL-3.0-or-later",
-            "optional": true,
-            "os": [
-                "win32"
-            ],
-            "peer": true,
-            "engines": {
-                "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
-            },
-            "funding": {
-                "url": "https://opencollective.com/libvips"
-            }
-        },
-        "node_modules/@img/sharp-win32-x64": {
-            "version": "0.34.3",
-            "resolved": "https://registry.npmjs.org/@img/sharp-win32-x64/-/sharp-win32-x64-0.34.3.tgz",
-            "integrity": "sha512-OWwz05d++TxzLEv4VnsTz5CmZ6mI6S05sfQGEMrNrQcOEERbX46332IvE7pO/EUiw7jUrrS40z/M7kPyjfl04g==",
-            "cpu": [
-                "x64"
-            ],
-            "dev": true,
-            "license": "Apache-2.0 AND LGPL-3.0-or-later",
-            "optional": true,
-            "os": [
-                "win32"
-            ],
-            "peer": true,
-            "engines": {
-                "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
-            },
-            "funding": {
-                "url": "https://opencollective.com/libvips"
-            }
-        },
         "node_modules/@isaacs/cliui": {
             "version": "8.0.2",
             "resolved": "https://registry.npmjs.org/@isaacs/cliui/-/cliui-8.0.2.tgz",
@@ -28859,61 +28385,6 @@
             "integrity": "sha512-y0m1JoUZSlPAjXVtPPW70aZWfIL/dSP7AFkRnniLCrK/8MDKog3TySTBmckD+RObVxH0v4Tox67+F14PdED2oQ==",
             "license": "MIT"
         },
-        "node_modules/sharp": {
-            "version": "0.34.3",
-            "resolved": "https://registry.npmjs.org/sharp/-/sharp-0.34.3.tgz",
-            "integrity": "sha512-eX2IQ6nFohW4DbvHIOLRB3MHFpYqaqvXd3Tp5e/T/dSH83fxaNJQRvDMhASmkNTsNTVF2/OOopzRCt7xokgPfg==",
-            "hasInstallScript": true,
-            "license": "Apache-2.0",
-            "optional": true,
-            "peer": true,
-            "dependencies": {
-                "color": "^4.2.3",
-                "detect-libc": "^2.0.4",
-                "semver": "^7.7.2"
-            },
-            "engines": {
-                "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
-            },
-            "funding": {
-                "url": "https://opencollective.com/libvips"
-            },
-            "optionalDependencies": {
-                "@img/sharp-darwin-arm64": "0.34.3",
-                "@img/sharp-darwin-x64": "0.34.3",
-                "@img/sharp-libvips-darwin-arm64": "1.2.0",
-                "@img/sharp-libvips-darwin-x64": "1.2.0",
-                "@img/sharp-libvips-linux-arm": "1.2.0",
-                "@img/sharp-libvips-linux-arm64": "1.2.0",
-                "@img/sharp-libvips-linux-ppc64": "1.2.0",
-                "@img/sharp-libvips-linux-s390x": "1.2.0",
-                "@img/sharp-libvips-linux-x64": "1.2.0",
-                "@img/sharp-libvips-linuxmusl-arm64": "1.2.0",
-                "@img/sharp-libvips-linuxmusl-x64": "1.2.0",
-                "@img/sharp-linux-arm": "0.34.3",
-                "@img/sharp-linux-arm64": "0.34.3",
-                "@img/sharp-linux-ppc64": "0.34.3",
-                "@img/sharp-linux-s390x": "0.34.3",
-                "@img/sharp-linux-x64": "0.34.3",
-                "@img/sharp-linuxmusl-arm64": "0.34.3",
-                "@img/sharp-linuxmusl-x64": "0.34.3",
-                "@img/sharp-wasm32": "0.34.3",
-                "@img/sharp-win32-arm64": "0.34.3",
-                "@img/sharp-win32-ia32": "0.34.3",
-                "@img/sharp-win32-x64": "0.34.3"
-            }
-        },
-        "node_modules/sharp/node_modules/detect-libc": {
-            "version": "2.0.4",
-            "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.0.4.tgz",
-            "integrity": "sha512-3UDv+G9CsCKO1WKMGw9fwq/SWJYbI0c5Y7LU1AXYoDdbhE2AHQ6N6Nb34sG8Fj7T5APy8qXDCKuuIHd1BR0tVA==",
-            "license": "Apache-2.0",
-            "optional": true,
-            "peer": true,
-            "engines": {
-                "node": ">=8"
-            }
-        },
         "node_modules/shebang-command": {
             "version": "2.0.0",
             "resolved": "https://registry.npmjs.org/shebang-command/-/shebang-command-2.0.0.tgz",
@@ -29790,46 +29261,6 @@
             "integrity": "sha512-e4hG1hRwoOdRb37cIMSgzNsxyzKfayW6VOflrwvR+/bzrkyxY/31WkbgnQpgtrNp1SdpJvpUAGTa/ZoiPNDuRQ==",
             "license": "MIT"
         },
-        "node_modules/svgo": {
-            "version": "4.0.0",
-            "resolved": "https://registry.npmjs.org/svgo/-/svgo-4.0.0.tgz",
-            "integrity": "sha512-VvrHQ+9uniE+Mvx3+C9IEe/lWasXCU0nXMY2kZeLrHNICuRiC8uMPyM14UEaMOFA5mhyQqEkB02VoQ16n3DLaw==",
-            "dev": true,
-            "license": "MIT",
-            "optional": true,
-            "peer": true,
-            "dependencies": {
-                "commander": "^11.1.0",
-                "css-select": "^5.1.0",
-                "css-tree": "^3.0.1",
-                "css-what": "^6.1.0",
-                "csso": "^5.0.5",
-                "picocolors": "^1.1.1",
-                "sax": "^1.4.1"
-            },
-            "bin": {
-                "svgo": "bin/svgo.js"
-            },
-            "engines": {
-                "node": ">=16"
-            },
-            "funding": {
-                "type": "opencollective",
-                "url": "https://opencollective.com/svgo"
-            }
-        },
-        "node_modules/svgo/node_modules/commander": {
-            "version": "11.1.0",
-            "resolved": "https://registry.npmjs.org/commander/-/commander-11.1.0.tgz",
-            "integrity": "sha512-yPVavfyCcRhmorC7rWlkHn15b4wDVgVmBA7kV4QVBsF7kv/9TKJAbAXVTxvTnwP8HHKjRCJDClKbciiYS7p0DQ==",
-            "dev": true,
-            "license": "MIT",
-            "optional": true,
-            "peer": true,
-            "engines": {
-                "node": ">=16"
-            }
-        },
         "node_modules/swr": {
             "version": "2.4.1",
             "resolved": "https://registry.npmjs.org/swr/-/swr-2.4.1.tgz",
@@ -31811,7 +31242,7 @@
         },
         "node_modules/uuid": {
             "version": "14.0.0",
-            "resolved": "https://registry.npmjs.org/uuid/-/uuid-14.0.0.tgz",
+            "resolved": "https://registry.npmmirror.com/uuid/-/uuid-14.0.0.tgz",
             "integrity": "sha512-Qo+uWgilfSmAhXCMav1uYFynlQO7fMFiMVZsQqZRMIXp0O7rR7qjkj+cPvBHLgBqi960QCoo/PH2/6ZtVqKvrg==",
             "funding": [
                 "https://github.com/sponsors/broofa",
diff --git a/package.json b/package.json
index 4c1d56798f..367cf0d7e7 100644
--- a/package.json
+++ b/package.json
@@ -130,7 +130,7 @@
         "throttle-debounce": "^5.0.2",
         "unist-util-visit": "^5.1.0",
         "use-device-pixel-ratio": "^1.1.2",
-        "uuid": "^14.0.0",
+        "uuid": "14.0.0",
         "winston": "^3.19.0",
         "ws": "^8.19.0",
         "yaml": "^2.8.3"

From ccc27504da2d919cc3330c3802d2d4fa105b5d3a Mon Sep 17 00:00:00 2001
From: lyx-tec <lyx.tec@gmail.com>
Date: Sat, 30 May 2026 09:58:42 +0800
Subject: [PATCH 2/3] feat: add Playwright E2E testing for Electron app (#3)
 (#4)

* wip

* add search input ref

* feat: add Playwright E2E testing (#3)

---------

Co-authored-by: carl2027 <carl.2027@outlook.com>
---
 .github/workflows/playwright.yml              | 34 ++++++++++
 e2e/helpers/launch.ts                         | 23 +++++++
 e2e/search-clipboard.spec.ts                  | 47 ++++++++++++++
 frontend/app/element/search.tsx               | 10 ++-
 frontend/app/store/keymodel.ts                | 25 ++++++++
 frontend/app/view/term/term.tsx               |  2 +
 .../changes/add-playwright-e2e/.openspec.yaml |  2 +
 openspec/changes/add-playwright-e2e/design.md | 41 ++++++++++++
 .../changes/add-playwright-e2e/proposal.md    | 30 +++++++++
 .../specs/e2e-search-clipboard/spec.md        | 17 +++++
 .../specs/playwright-electron-setup/spec.md   | 23 +++++++
 openspec/changes/add-playwright-e2e/tasks.md  | 15 +++++
 package-lock.json                             | 64 +++++++++++++++++++
 package.json                                  |  5 +-
 playwright.config.ts                          | 10 +++
 test-results/playwright/.last-run.json        |  4 ++
 16 files changed, 350 insertions(+), 2 deletions(-)
 create mode 100644 .github/workflows/playwright.yml
 create mode 100644 e2e/helpers/launch.ts
 create mode 100644 e2e/search-clipboard.spec.ts
 create mode 100644 openspec/changes/add-playwright-e2e/.openspec.yaml
 create mode 100644 openspec/changes/add-playwright-e2e/design.md
 create mode 100644 openspec/changes/add-playwright-e2e/proposal.md
 create mode 100644 openspec/changes/add-playwright-e2e/specs/e2e-search-clipboard/spec.md
 create mode 100644 openspec/changes/add-playwright-e2e/specs/playwright-electron-setup/spec.md
 create mode 100644 openspec/changes/add-playwright-e2e/tasks.md
 create mode 100644 playwright.config.ts
 create mode 100644 test-results/playwright/.last-run.json

diff --git a/.github/workflows/playwright.yml b/.github/workflows/playwright.yml
new file mode 100644
index 0000000000..9f6fe1241a
--- /dev/null
+++ b/.github/workflows/playwright.yml
@@ -0,0 +1,34 @@
+name: Playwright E2E Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: windows-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version: "1.25"
+
+      - name: Install Task
+        uses: arduino/setup-task@v2
+
+      - name: Install Zig
+        uses: mlugg/setup-zig@v1
+
+      - name: Build app
+        run: task package -- --win --x64 --config.win.target=zip
+
+      - name: Run E2E tests
+        run: npx playwright test
diff --git a/e2e/helpers/launch.ts b/e2e/helpers/launch.ts
new file mode 100644
index 0000000000..95d95f3383
--- /dev/null
+++ b/e2e/helpers/launch.ts
@@ -0,0 +1,23 @@
+import { _electron as electron, ElectronApplication, Page } from "@playwright/test";
+import * as path from "path";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+export const APP_PATH = path.resolve(__dirname, "../../make/win-unpacked/Wave.exe");
+
+export async function launchApp(): Promise<ElectronApplication> {
+    const app = await electron.launch({
+        executablePath: APP_PATH,
+        args: [],
+        env: {
+            ...process.env,
+            WAVETERM_NOCONFIRMQUIT: "1",
+        },
+    });
+    return app;
+}
+
+export async function getMainWindow(app: ElectronApplication): Promise<Page> {
+    return await app.firstWindow();
+}
diff --git a/e2e/search-clipboard.spec.ts b/e2e/search-clipboard.spec.ts
new file mode 100644
index 0000000000..b343c93e70
--- /dev/null
+++ b/e2e/search-clipboard.spec.ts
@@ -0,0 +1,47 @@
+import { ElectronApplication, Page } from "@playwright/test";
+import { test, expect } from "@playwright/test";
+import { launchApp } from "./helpers/launch";
+
+async function getMainWindow(app: ElectronApplication): Promise<Page> {
+    return await app.firstWindow();
+}
+
+async function setClipboard(app: ElectronApplication, text: string): Promise<void> {
+    await app.evaluate(({ clipboard }, txt) => clipboard.writeText(txt), text);
+}
+
+async function readClipboard(app: ElectronApplication): Promise<string> {
+    return await app.evaluate(({ clipboard }) => clipboard.readText());
+}
+
+test.describe("search + copy-on-select clipboard behavior", () => {
+    let app: ElectronApplication;
+    let window: Page;
+
+    test.beforeEach(async () => {
+        app = await launchApp();
+        window = await getMainWindow(app);
+    });
+
+    test.afterEach(async () => {
+        await app.close();
+    });
+
+    test("navigating search results should not overwrite clipboard", async () => {
+        await window.waitForTimeout(8000);
+
+        await setClipboard(app, "known-clipboard-content");
+        expect(await readClipboard(app)).toBe("known-clipboard-content");
+
+        await window.keyboard.press("Control+f");
+        await window.waitForTimeout(1000);
+
+        await window.keyboard.type("test");
+        await window.waitForTimeout(1000);
+
+        await window.keyboard.press("Enter");
+        await window.waitForTimeout(1000);
+
+        expect(await readClipboard(app)).toBe("known-clipboard-content");
+    });
+});
diff --git a/frontend/app/element/search.tsx b/frontend/app/element/search.tsx
index e09e8a1078..923ed464ce 100644
--- a/frontend/app/element/search.tsx
+++ b/frontend/app/element/search.tsx
@@ -11,6 +11,7 @@ import "./search.scss";
 
 type SearchProps = SearchAtoms & {
     anchorRef?: React.RefObject<HTMLElement>;
+    searchInputRef?: React.RefObject<HTMLInputElement>;
     offsetX?: number;
     offsetY?: number;
     onSearch?: (search: string) => void;
@@ -34,6 +35,8 @@ const SearchComponent = ({
     onNext,
     onPrev,
 }: SearchProps) => {
+    const localInputRef = useRef<HTMLInputElement>(null);
+    const inputRef = providedInputRef || localInputRef;
     const [isOpen, setIsOpen] = useAtom<boolean>(isOpenAtom);
     const [search, setSearch] = useAtom<string>(searchAtom);
     const [index, setIndex] = useAtom<number>(indexAtom);
@@ -198,6 +201,7 @@ export const Search = memo(SearchComponent) as typeof SearchComponent;
 
 type SearchOptions = {
     anchorRef?: React.RefObject<HTMLElement>;
+    searchInputRef?: React.RefObject<HTMLInputElement>;
     viewModel?: ViewModel;
     regex?: boolean;
     caseSensitive?: boolean;
@@ -219,15 +223,19 @@ export function useSearch(options?: SearchOptions): SearchProps {
         []
     );
     const anchorRef = options?.anchorRef ?? useRef(null);
+    const searchInputRef = options?.searchInputRef ?? useRef(null);
     useEffect(() => {
         if (options?.viewModel) {
             options.viewModel.searchAtoms = searchAtoms;
+            // Store searchInputRef on viewModel for external access (e.g., keymodel.ts)
+            (options.viewModel as any).searchInputRef = searchInputRef;
             return () => {
                 options.viewModel.searchAtoms = undefined;
+                (options.viewModel as any).searchInputRef = undefined;
             };
         }
     }, [options?.viewModel]);
-    return { ...searchAtoms, anchorRef };
+    return { ...searchAtoms, anchorRef, searchInputRef };
 }
 
 const createToggleButtonDecl = (
diff --git a/frontend/app/store/keymodel.ts b/frontend/app/store/keymodel.ts
index cca01753bb..02ced3d3ef 100644
--- a/frontend/app/store/keymodel.ts
+++ b/frontend/app/store/keymodel.ts
@@ -28,6 +28,7 @@ import { isWindows } from "@/util/platformutil";
 import { CHORD_TIMEOUT } from "@/util/sharedconst";
 import { fireAndForget } from "@/util/util";
 import * as jotai from "jotai";
+import { TermViewModel } from "../view/term/term-model";
 import { modalsModel } from "./modalmodel";
 import { isBuilderWindow, isTabWindow } from "./windowtype";
 
@@ -701,6 +702,30 @@ function registerGlobalKeys() {
             return true;
         });
     }
+    function getSelectedText(): string {
+        // Check for terminal selection first
+        const bcm = getBlockComponentModel(getFocusedBlockInStaticTab());
+        if (bcm?.viewModel?.viewType === "term") {
+            const termViewModel = bcm.viewModel as TermViewModel;
+            if (termViewModel.termRef?.current?.terminal) {
+                const terminalSelection = termViewModel.termRef.current.terminal.getSelection();
+                if (terminalSelection && terminalSelection.length > 0) {
+                    return terminalSelection.trim();
+                }
+            }
+        }
+
+        // Check for regular text selection
+        const selection = window.getSelection();
+        if (selection && selection.rangeCount > 0 && !selection.isCollapsed) {
+            const selectedText = selection.toString().trim();
+            if (selectedText.length > 0) {
+                return selectedText;
+            }
+        }
+        return "";
+    }
+
     function activateSearch(event: WaveKeyboardEvent): boolean {
         const bcm = getBlockComponentModel(getFocusedBlockInStaticTab());
         // Ctrl+f is reserved in most shells
diff --git a/frontend/app/view/term/term.tsx b/frontend/app/view/term/term.tsx
index 67eb5737c6..a9dcd17bf0 100644
--- a/frontend/app/view/term/term.tsx
+++ b/frontend/app/view/term/term.tsx
@@ -200,8 +200,10 @@ const TerminalView = ({ blockId, model }: ViewComponentProps<TermViewModel>) =>
     const isBasicTerm = termMode != "vdom" && blockData?.meta?.controller != "cmd"; // needs to match isBasicTerm
 
     // search
+    const searchInputRef = React.useRef<HTMLInputElement>(null);
     const searchProps = useSearch({
         anchorRef: viewRef,
+        searchInputRef: searchInputRef,
         viewModel: model,
         caseSensitive: false,
         wholeWord: false,
diff --git a/openspec/changes/add-playwright-e2e/.openspec.yaml b/openspec/changes/add-playwright-e2e/.openspec.yaml
new file mode 100644
index 0000000000..b44fb0ec50
--- /dev/null
+++ b/openspec/changes/add-playwright-e2e/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-05-30
diff --git a/openspec/changes/add-playwright-e2e/design.md b/openspec/changes/add-playwright-e2e/design.md
new file mode 100644
index 0000000000..103378983f
--- /dev/null
+++ b/openspec/changes/add-playwright-e2e/design.md
@@ -0,0 +1,41 @@
+## Context
+
+WaveTerm's UI testing is limited to a single TestDriver.ai onboarding scenario that runs only in CI. For the copy-on-select fix and future UI changes, we need fast, local, reliable E2E tests. Playwright with Electron support is the standard choice.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Add Playwright with Electron support as dev dependency
+- Create a config that works with both dev mode (`electron-vite dev`) and packaged app
+- Write a test verifying the search + copy-on-select clipboard fix
+- Ensure tests can run locally without CI dependencies
+
+**Non-Goals:**
+- Full UI coverage of all features (future work)
+- Replacing existing TestDriver.ai tests
+- Testing backend/Go code
+
+## Decisions
+
+**Decision: Launch Electron app via direct binary for testing**
+
+Use Playwright's `_electron.launch()` with the packaged app executable. This avoids the complexity of hooking into `electron-vite dev` hot-reload.
+
+For local development, users can run `task package -- --win --x64 --config.win.target=zip` to produce a portable build, then run tests against it.
+
+- Alternative considered: Launching via `electron-vite dev` — harder to detect ready state, slower
+- Alternative considered: Using `electron-vite preview` — still requires a build step
+
+**Decision: No global test fixtures for now**
+
+Keep tests self-contained with a shared launch helper. Avoid complex fixture setup until more tests exist.
+
+**Decision: Tests in `e2e/` at project root**
+
+Follow Playwright conventions. Place in `e2e/` not `frontend/e2e/` since tests cover the full Electron app.
+
+## Risks / Trade-offs
+
+- **Build needed**: Tests require a packaged build first (can be automated in CI)
+- **Windows focus**: Initial setup targets Windows (current platform); other platforms can be added later
+- **No hot reload**: Unlike TestDriver.ai, Playwright tests launch the full app binary
diff --git a/openspec/changes/add-playwright-e2e/proposal.md b/openspec/changes/add-playwright-e2e/proposal.md
new file mode 100644
index 0000000000..6ceaa5df44
--- /dev/null
+++ b/openspec/changes/add-playwright-e2e/proposal.md
@@ -0,0 +1,30 @@
+## Why
+
+WaveTerm currently has no UI automated testing. The only E2E test uses TestDriver.ai (CI-only, single onboarding scenario). Manual testing is required for every UI bug fix. Introducing Playwright enables fast, reliable, locally-runnable UI tests for the terminal and core UI components.
+
+## What Changes
+
+- Add `@playwright/test` as dev dependency
+- Create Playwright configuration for Electron app testing
+- Write E2E test for the recently fixed search + copy-on-select clipboard bug
+- Set up a test helper for launching the Electron app (both dev mode and packaged)
+- Add npm scripts for running Playwright tests
+- Add CI workflow for running Playwright tests on PRs
+
+## Capabilities
+
+### New Capabilities
+
+- `playwright-electron-setup`: Playwright config targeting WaveTerm's Electron app, with launch helpers for dev/packaged modes
+- `e2e-search-clipboard`: E2E test coverage for the copy-on-select clipboard behavior when search is open
+
+### Modified Capabilities
+
+- `<existing-name>`: no spec-level requirement changes
+
+## Impact
+
+- `package.json` — new devDependency `@playwright/test`, new scripts
+- `playwright.config.ts` — new Playwright configuration file (project root)
+- `e2e/` — new directory with test specs and helpers
+- `.github/workflows/playwright.yml` — new CI workflow (optional)
diff --git a/openspec/changes/add-playwright-e2e/specs/e2e-search-clipboard/spec.md b/openspec/changes/add-playwright-e2e/specs/e2e-search-clipboard/spec.md
new file mode 100644
index 0000000000..35e60e3d79
--- /dev/null
+++ b/openspec/changes/add-playwright-e2e/specs/e2e-search-clipboard/spec.md
@@ -0,0 +1,17 @@
+## ADDED Requirements
+
+### Requirement: Search + copy-on-select clipboard test
+
+The system SHALL have an E2E test that verifies the fix for copy-on-select not overwriting clipboard when search is open.
+
+#### Scenario: Clipboard not overwritten during search navigation
+- **GIVEN** `term:copyonselect` is enabled
+- **WHEN** user opens search (Ctrl+F) and types text
+- **WHEN** user navigates through search results
+- **THEN** the clipboard SHALL NOT contain the terminal selection text
+
+#### Scenario: Copy-on-select works when search is closed
+- **GIVEN** `term:copyonselect` is enabled
+- **WHEN** search is closed
+- **WHEN** user selects text in the terminal
+- **THEN** the clipboard SHALL contain the selected text
diff --git a/openspec/changes/add-playwright-e2e/specs/playwright-electron-setup/spec.md b/openspec/changes/add-playwright-e2e/specs/playwright-electron-setup/spec.md
new file mode 100644
index 0000000000..d2b7e9dfd1
--- /dev/null
+++ b/openspec/changes/add-playwright-e2e/specs/playwright-electron-setup/spec.md
@@ -0,0 +1,23 @@
+## ADDED Requirements
+
+### Requirement: Playwright configuration for Electron
+
+The system SHALL provide a Playwright configuration that can launch the WaveTerm Electron app for testing.
+
+#### Scenario: Dev mode launch
+- **WHEN** running `npx playwright test` in dev mode
+- **THEN** the test framework SHALL launch WaveTerm via `electron-vite dev`
+- **AND** wait for the app window to be ready before running tests
+
+#### Scenario: Packaged app launch
+- **WHEN** running Playwright against a packaged build
+- **THEN** the test framework SHALL launch the Wave.exe binary directly
+- **AND** wait for the window to be ready
+
+### Requirement: Test organization
+
+E2E tests SHALL be organized in an `e2e/` directory at the project root, with shared helpers in `e2e/helpers/`.
+
+#### Scenario: Directory structure
+- **WHEN** viewing the `e2e/` directory
+- **THEN** it SHALL contain spec files and a `helpers/` subdirectory with launch utilities
diff --git a/openspec/changes/add-playwright-e2e/tasks.md b/openspec/changes/add-playwright-e2e/tasks.md
new file mode 100644
index 0000000000..96725937a3
--- /dev/null
+++ b/openspec/changes/add-playwright-e2e/tasks.md
@@ -0,0 +1,15 @@
+## 1. Setup
+
+- [x] 1.1 Install Playwright and Electron support: `npm install -D @playwright/test` and install Electron support
+- [x] 1.2 Create `playwright.config.ts` with Electron launch configuration
+- [x] 1.3 Create `e2e/helpers/launch.ts` — shared helper for launching WaveTerm app
+
+## 2. Test Implementation
+
+- [x] 2.1 Write `e2e/search-clipboard.spec.ts` — search + copy-on-select clipboard test
+- [x] 2.2 Verify test passes against a packaged build
+
+## 3. Integration
+
+- [x] 3.1 Add npm scripts: `npm run test:e2e` and `npm run test:e2e:build`
+- [x] 3.2 Create `.github/workflows/playwright.yml` CI workflow
diff --git a/package-lock.json b/package-lock.json
index fdf8623be7..05925b3641 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -83,6 +83,7 @@
             },
             "devDependencies": {
                 "@eslint/js": "^9.39",
+                "@playwright/test": "1.60.0",
                 "@rollup/plugin-node-resolve": "^16.0.3",
                 "@tailwindcss/vite": "^4.2.1",
                 "@types/css-tree": "^2",
@@ -6691,6 +6692,22 @@
                 "url": "https://opencollective.com/pkgr"
             }
         },
+        "node_modules/@playwright/test": {
+            "version": "1.60.0",
+            "resolved": "https://registry.npmmirror.com/@playwright/test/-/test-1.60.0.tgz",
+            "integrity": "sha512-O71yZIbAh/PxDMNGns37GHBIfrVkEVyn+AXyIa5dOTfb4/xNvRWV+Vv/NMbNCtODB/pO7vLlF2OTmMVLhmr7Ag==",
+            "dev": true,
+            "license": "Apache-2.0",
+            "dependencies": {
+                "playwright": "1.60.0"
+            },
+            "bin": {
+                "playwright": "cli.js"
+            },
+            "engines": {
+                "node": ">=18"
+            }
+        },
         "node_modules/@pnpm/config.env-replace": {
             "version": "1.1.0",
             "resolved": "https://registry.npmjs.org/@pnpm/config.env-replace/-/config.env-replace-1.1.0.tgz",
@@ -23614,6 +23631,53 @@
                 "pathe": "^2.0.3"
             }
         },
+        "node_modules/playwright": {
+            "version": "1.60.0",
+            "resolved": "https://registry.npmmirror.com/playwright/-/playwright-1.60.0.tgz",
+            "integrity": "sha512-hheHdokM8cdqCb0lcE3s+zT4t4W+vvjpGxsZlDnikarzx8tSzMebh3UiFtgqwFwnTnjYQcsyMF8ei2mCO/tpeA==",
+            "dev": true,
+            "license": "Apache-2.0",
+            "dependencies": {
+                "playwright-core": "1.60.0"
+            },
+            "bin": {
+                "playwright": "cli.js"
+            },
+            "engines": {
+                "node": ">=18"
+            },
+            "optionalDependencies": {
+                "fsevents": "2.3.2"
+            }
+        },
+        "node_modules/playwright-core": {
+            "version": "1.60.0",
+            "resolved": "https://registry.npmmirror.com/playwright-core/-/playwright-core-1.60.0.tgz",
+            "integrity": "sha512-9bW6zvX/m0lEbgTKJ6YppOKx8H3VOPBMOCFh2irXFOT4BbHgrx5hPjwJYLT40Lu+4qtD36qKc/Hn56StUW57IA==",
+            "dev": true,
+            "license": "Apache-2.0",
+            "bin": {
+                "playwright-core": "cli.js"
+            },
+            "engines": {
+                "node": ">=18"
+            }
+        },
+        "node_modules/playwright/node_modules/fsevents": {
+            "version": "2.3.2",
+            "resolved": "https://registry.npmmirror.com/fsevents/-/fsevents-2.3.2.tgz",
+            "integrity": "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==",
+            "dev": true,
+            "hasInstallScript": true,
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "darwin"
+            ],
+            "engines": {
+                "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
+            }
+        },
         "node_modules/plist": {
             "version": "3.1.0",
             "resolved": "https://registry.npmjs.org/plist/-/plist-3.1.0.tgz",
diff --git a/package.json b/package.json
index 367cf0d7e7..f80607177e 100644
--- a/package.json
+++ b/package.json
@@ -25,10 +25,13 @@
         "build:prod": "electron-vite build --mode production",
         "coverage": "vitest run --coverage",
         "test": "vitest",
-        "postinstall": "node ./postinstall.cjs"
+        "postinstall": "node ./postinstall.cjs",
+        "test:e2e": "playwright test",
+        "test:e2e:build": "task package -- --win --x64 --config.win.target=zip && playwright test"
     },
     "devDependencies": {
         "@eslint/js": "^9.39",
+        "@playwright/test": "1.60.0",
         "@rollup/plugin-node-resolve": "^16.0.3",
         "@tailwindcss/vite": "^4.2.1",
         "@types/css-tree": "^2",
diff --git a/playwright.config.ts b/playwright.config.ts
new file mode 100644
index 0000000000..61ad1c5795
--- /dev/null
+++ b/playwright.config.ts
@@ -0,0 +1,10 @@
+import { defineConfig } from "@playwright/test";
+
+export default defineConfig({
+    testDir: "./e2e",
+    timeout: 90000,
+    expect: { timeout: 15000 },
+    retries: 0,
+    reporter: [["list"], ["html", { outputFolder: "playwright-report" }]],
+    outputDir: "test-results/playwright",
+});
diff --git a/test-results/playwright/.last-run.json b/test-results/playwright/.last-run.json
new file mode 100644
index 0000000000..cbcc1fbac1
--- /dev/null
+++ b/test-results/playwright/.last-run.json
@@ -0,0 +1,4 @@
+{
+  "status": "passed",
+  "failedTests": []
+}
\ No newline at end of file

From 06d31be5a7e1d679cc6a191aa9ff1783adfa0543 Mon Sep 17 00:00:00 2001
From: lyx-tec <lyx.tec@gmail.com>
Date: Tue, 2 Jun 2026 23:32:16 +0800
Subject: [PATCH 3/3] fix: add ProxyCommand support for SSH connections

WaveTerm previously ignored the ProxyCommand directive in ~/.ssh/config,
causing connections via SSH config Host entries with ProxyCommand to fail
with 'Disconnected from xxx'.

This change:
- Parses ProxyCommand from SSH config in findSshConfigKeywords
- Executes the proxy command via os/exec with %h/%p/%r expansion
- Wraps command stdin/stdout as net.Conn via net.Pipe()
- Cleans up the subprocess on connection close via proxyCommandConn

Affects: pkg/wconfig/settingsconfig.go, pkg/remote/sshclient.go,
frontend/types/gotypes.d.ts
---
 frontend/types/gotypes.d.ts   |  1 +
 pkg/remote/sshclient.go       | 75 +++++++++++++++++++++++++++++++++--
 pkg/wconfig/settingsconfig.go |  1 +
 3 files changed, 74 insertions(+), 3 deletions(-)

diff --git a/frontend/types/gotypes.d.ts b/frontend/types/gotypes.d.ts
index b3220ab6d1..bb07f466b0 100644
--- a/frontend/types/gotypes.d.ts
+++ b/frontend/types/gotypes.d.ts
@@ -852,6 +852,7 @@ declare global {
         "ssh:identityagent"?: string;
         "ssh:identitiesonly"?: boolean;
         "ssh:proxyjump"?: string[];
+        "ssh:proxycommand"?: string;
         "ssh:userknownhostsfile"?: string[];
         "ssh:globalknownhostsfile"?: string[];
     };
diff --git a/pkg/remote/sshclient.go b/pkg/remote/sshclient.go
index b1c9faca21..23983e9eb2 100644
--- a/pkg/remote/sshclient.go
+++ b/pkg/remote/sshclient.go
@@ -838,10 +838,49 @@ func createClientConfig(connCtx context.Context, sshKeywords *wconfig.ConnKeywor
 	}, nil
 }
 
-func connectInternal(ctx context.Context, networkAddr string, clientConfig *ssh.ClientConfig, currentClient *ssh.Client) (*ssh.Client, error) {
+func expandProxyCommand(tmpl string, host string, port string, user string) string {
+	r := strings.NewReplacer(
+		"%h", host,
+		"%p", port,
+		"%r", user,
+		"%%", "%",
+	)
+	return r.Replace(tmpl)
+}
+
+func connectInternal(ctx context.Context, networkAddr string, clientConfig *ssh.ClientConfig, currentClient *ssh.Client, proxyCmd string) (*ssh.Client, error) {
 	var clientConn net.Conn
 	var err error
-	if currentClient == nil {
+
+	if proxyCmd != "" {
+		host, port, _ := net.SplitHostPort(networkAddr)
+		user := clientConfig.User
+		expandedCmd := expandProxyCommand(proxyCmd, host, port, user)
+		blocklogger.Infof(ctx, "[conndebug] ssh proxycommand: %s\n", expandedCmd)
+
+		var cmd *exec.Cmd
+		if runtime.GOOS == "windows" {
+			cmd = exec.CommandContext(ctx, "cmd", "/c", expandedCmd)
+		} else {
+			cmd = exec.CommandContext(ctx, "sh", "-c", expandedCmd)
+		}
+		local, remote := net.Pipe()
+		cmd.Stdin = remote
+		cmd.Stdout = remote
+		cmd.Stderr = remote
+
+		err = cmd.Start()
+		if err != nil {
+			remote.Close()
+			local.Close()
+			return nil, utilds.MakeSubCodedError(ConnErrCode_Dial, "proxycmd-start", err)
+		}
+		clientConn = &proxyCommandConn{
+			Conn:   local,
+			cmd:    cmd,
+			remote: remote,
+		}
+	} else if currentClient == nil {
 		d := net.Dialer{Timeout: clientConfig.Timeout}
 		blocklogger.Infof(ctx, "[conndebug] ssh dial %s\n", networkAddr)
 		clientConn, err = d.DialContext(ctx, "tcp", networkAddr)
@@ -868,6 +907,22 @@ func connectInternal(ctx context.Context, networkAddr string, clientConfig *ssh.
 	return ssh.NewClient(c, chans, reqs), nil
 }
 
+// proxyCommandConn wraps a net.Pipe connection with an os/exec Cmd.
+// When the connection is closed, the remote pipe end is closed and the
+// command process is waited on (reaped) in the background.
+type proxyCommandConn struct {
+	net.Conn
+	cmd    *exec.Cmd
+	remote net.Conn
+}
+
+func (pcc *proxyCommandConn) Close() error {
+	pcc.remote.Close()
+	err := pcc.Conn.Close()
+	go pcc.cmd.Wait()
+	return err
+}
+
 func ConnectToClient(connCtx context.Context, opts *SSHOpts, currentClient *ssh.Client, jumpNum int32, connFlags *wconfig.ConnKeywords) (*ssh.Client, int32, error) {
 	blocklogger.Infof(connCtx, "[conndebug] ConnectToClient %s (jump:%d)...\n", opts.String(), jumpNum)
 	debugInfo := &ConnectionDebugInfo{
@@ -950,8 +1005,9 @@ func ConnectToClient(connCtx context.Context, opts *SSHOpts, currentClient *ssh.
 	if err != nil {
 		return nil, debugInfo.JumpNum, ConnectionError{ConnectionDebugInfo: debugInfo, Err: err}
 	}
+	proxyCmd := utilfn.SafeDeref(sshKeywords.SshProxyCommand)
 	networkAddr := utilfn.SafeDeref(sshKeywords.SshHostName) + ":" + utilfn.SafeDeref(sshKeywords.SshPort)
-	client, err := connectInternal(connCtx, networkAddr, clientConfig, debugInfo.CurrentClient)
+	client, err := connectInternal(connCtx, networkAddr, clientConfig, debugInfo.CurrentClient, proxyCmd)
 	if err != nil {
 		return client, debugInfo.JumpNum, ConnectionError{ConnectionDebugInfo: debugInfo, Err: err}
 	}
@@ -1100,6 +1156,15 @@ func findSshConfigKeywords(hostPattern string) (connKeywords *wconfig.ConnKeywor
 		}
 		sshKeywords.SshProxyJump = append(sshKeywords.SshProxyJump, proxyJumpName)
 	}
+
+	proxyCommandRaw, err := WaveSshConfigUserSettings().GetStrict(hostPattern, "ProxyCommand")
+	if err != nil {
+		return nil, err
+	}
+	proxyCommandClean := trimquotes.TryTrimQuotes(proxyCommandRaw)
+	if proxyCommandClean != "" {
+		sshKeywords.SshProxyCommand = &proxyCommandClean
+	}
 	rawUserKnownHostsFile, _ := WaveSshConfigUserSettings().GetStrict(hostPattern, "UserKnownHostsFile")
 	sshKeywords.SshUserKnownHostsFile = strings.Fields(rawUserKnownHostsFile) // TODO - smarter splitting escaped spaces and quotes
 	rawGlobalKnownHostsFile, _ := WaveSshConfigUserSettings().GetStrict(hostPattern, "GlobalKnownHostsFile")
@@ -1130,6 +1195,7 @@ func findSshDefaults(hostPattern string) (connKeywords *wconfig.ConnKeywords, ou
 	sshKeywords.SshProxyJump = []string{}
 	sshKeywords.SshUserKnownHostsFile = strings.Fields(ssh_config.Default("UserKnownHostsFile"))
 	sshKeywords.SshGlobalKnownHostsFile = strings.Fields(ssh_config.Default("GlobalKnownHostsFile"))
+	sshKeywords.SshProxyCommand = nil
 	return sshKeywords, nil
 }
 
@@ -1197,6 +1263,9 @@ func mergeKeywords(oldKeywords *wconfig.ConnKeywords, newKeywords *wconfig.ConnK
 	if newKeywords.SshProxyJump != nil {
 		outKeywords.SshProxyJump = newKeywords.SshProxyJump
 	}
+	if newKeywords.SshProxyCommand != nil {
+		outKeywords.SshProxyCommand = newKeywords.SshProxyCommand
+	}
 	if newKeywords.SshUserKnownHostsFile != nil {
 		outKeywords.SshUserKnownHostsFile = newKeywords.SshUserKnownHostsFile
 	}
diff --git a/pkg/wconfig/settingsconfig.go b/pkg/wconfig/settingsconfig.go
index 67118b1670..831dbb6623 100644
--- a/pkg/wconfig/settingsconfig.go
+++ b/pkg/wconfig/settingsconfig.go
@@ -419,6 +419,7 @@ type ConnKeywords struct {
 	SshIdentityAgent                *string  `json:"ssh:identityagent,omitempty"`
 	SshIdentitiesOnly               *bool    `json:"ssh:identitiesonly,omitempty"`
 	SshProxyJump                    []string `json:"ssh:proxyjump,omitempty"`
+	SshProxyCommand                 *string  `json:"ssh:proxycommand,omitempty"`
 	SshUserKnownHostsFile           []string `json:"ssh:userknownhostsfile,omitempty"`
 	SshGlobalKnownHostsFile         []string `json:"ssh:globalknownhostsfile,omitempty"`
 }