From cf287d4990387eb01a0abeb5215d92fa35e9c4ee Mon Sep 17 00:00:00 2001
From: Joao Porta <jpedro.porta@gmail.com>
Date: Tue, 14 Jul 2026 10:12:37 -0300
Subject: [PATCH] update

---
 .opencode/commands/opsx-apply.md              | 152 ++++++++++
 .opencode/commands/opsx-archive.md            | 157 ++++++++++
 .opencode/commands/opsx-explore.md            | 169 +++++++++++
 .opencode/commands/opsx-propose.md            | 104 +++++++
 .opencode/commands/opsx-sync.md               | 140 +++++++++
 .../skills/openspec-apply-change/SKILL.md     | 159 ++++++++++
 .../skills/openspec-archive-change/SKILL.md   | 117 +++++++
 .opencode/skills/openspec-explore/SKILL.md    | 287 ++++++++++++++++++
 .opencode/skills/openspec-propose/SKILL.md    | 111 +++++++
 .opencode/skills/openspec-sync-specs/SKILL.md | 147 +++++++++
 modules/home-manager/nvim/nvim/lazy-lock.json |  15 +-
 .../nvim/nvim/lua/jpporta/macros.lua          |   8 +-
 .../lua/{plugin_bkp => plugins}/obsidian.lua  |  77 ++---
 .../nvim/nvim/lua/plugins/wiki.lua            |   9 -
 .../home-manager/nvim/nvim/lua/plugins/zk.lua |  25 --
 modules/home-manager/tmux/tmux.conf           |   2 +-
 .../2026-07-13-theme-switch/.openspec.yaml    |   2 +
 .../archive/2026-07-13-theme-switch/design.md | 160 ++++++++++
 .../2026-07-13-theme-switch/proposal.md       |  50 +++
 .../specs/theme-colors-sources/spec.md        |  85 ++++++
 .../specs/theme-switch/spec.md                | 155 ++++++++++
 .../archive/2026-07-13-theme-switch/tasks.md  |  91 ++++++
 openspec/config.yaml                          |   4 +
 23 files changed, 2147 insertions(+), 79 deletions(-)
 create mode 100644 .opencode/commands/opsx-apply.md
 create mode 100644 .opencode/commands/opsx-archive.md
 create mode 100644 .opencode/commands/opsx-explore.md
 create mode 100644 .opencode/commands/opsx-propose.md
 create mode 100644 .opencode/commands/opsx-sync.md
 create mode 100644 .opencode/skills/openspec-apply-change/SKILL.md
 create mode 100644 .opencode/skills/openspec-archive-change/SKILL.md
 create mode 100644 .opencode/skills/openspec-explore/SKILL.md
 create mode 100644 .opencode/skills/openspec-propose/SKILL.md
 create mode 100644 .opencode/skills/openspec-sync-specs/SKILL.md
 rename modules/home-manager/nvim/nvim/lua/{plugin_bkp => plugins}/obsidian.lua (77%)
 delete mode 100644 modules/home-manager/nvim/nvim/lua/plugins/wiki.lua
 delete mode 100644 modules/home-manager/nvim/nvim/lua/plugins/zk.lua
 create mode 100644 openspec/changes/archive/2026-07-13-theme-switch/.openspec.yaml
 create mode 100644 openspec/changes/archive/2026-07-13-theme-switch/design.md
 create mode 100644 openspec/changes/archive/2026-07-13-theme-switch/proposal.md
 create mode 100644 openspec/changes/archive/2026-07-13-theme-switch/specs/theme-colors-sources/spec.md
 create mode 100644 openspec/changes/archive/2026-07-13-theme-switch/specs/theme-switch/spec.md
 create mode 100644 openspec/changes/archive/2026-07-13-theme-switch/tasks.md
 create mode 100644 openspec/config.yaml

diff --git a/.opencode/commands/opsx-apply.md b/.opencode/commands/opsx-apply.md
new file mode 100644
index 0000000..9d0f3fc
--- /dev/null
+++ b/.opencode/commands/opsx-apply.md
@@ -0,0 +1,152 @@
+---
+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")
+   - `planningHome`, `changeRoot`, and `actionContext`: planning scope and edit constraints
+   - 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
+
+   **Workspace guard:** If status JSON reports `actionContext.mode: "workspace-planning"` and `allowedEditRoots` is empty, explain that full workspace apply is not supported in this slice. Treat linked repos and folders as read-only context, ask the user to select an affected area through an explicit implementation workflow, and STOP before editing files.
+
+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/.opencode/commands/opsx-archive.md b/.opencode/commands/opsx-archive.md
new file mode 100644
index 0000000..8f4e144
--- /dev/null
+++ b/.opencode/commands/opsx-archive.md
@@ -0,0 +1,157 @@
+---
+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
+   - `planningHome`, `changeRoot`, `artifactPaths`, and `actionContext`: path and scope context
+   - `artifacts`: List of artifacts with their status (`done` or other)
+
+   If status reports `actionContext.mode: "workspace-planning"`, explain that workspace archive is not supported in this slice and STOP. Do not move workspace changes into repo-local archives or edit linked repos.
+
+   **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**
+
+   Use `artifactPaths.specs.existingOutputPaths` from status JSON to check for delta 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 an `archive` directory under `planningHome.changesDir` if it doesn't exist:
+   ```bash
+   mkdir -p "<planningHome.changesDir>/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 `changeRoot` to the archive directory
+
+   ```bash
+   mv "<changeRoot>" "<planningHome.changesDir>/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:** the archive path derived from `planningHome.changesDir`/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:** the archive path derived from `planningHome.changesDir`/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:** the archive path derived from `planningHome.changesDir`/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:** the archive path derived from `planningHome.changesDir`/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/.opencode/commands/opsx-explore.md b/.opencode/commands/opsx-explore.md
new file mode 100644
index 0000000..a4ed088
--- /dev/null
+++ b/.opencode/commands/opsx-explore.md
@@ -0,0 +1,169 @@
+---
+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. **Resolve and read existing artifacts for context**
+   - Run `openspec status --change "<name>" --json`.
+   - Use `changeRoot`, `artifactPaths`, and `actionContext` from the status JSON.
+   - Read existing files from `artifactPaths.<artifact>.existingOutputPaths`.
+
+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/.opencode/commands/opsx-propose.md b/.opencode/commands/opsx-propose.md
new file mode 100644
index 0000000..f100115
--- /dev/null
+++ b/.opencode/commands/opsx-propose.md
@@ -0,0 +1,104 @@
+---
+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 in the planning home resolved by the CLI 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
+   - `planningHome`, `changeRoot`, `artifactPaths`, and `actionContext`: path and scope context. Use these instead of assuming repo-local paths.
+
+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
+        - `resolvedOutputPath`: Resolved path or pattern 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 and write it to `resolvedOutputPath`
+      - 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/.opencode/commands/opsx-sync.md b/.opencode/commands/opsx-sync.md
new file mode 100644
index 0000000..bbde982
--- /dev/null
+++ b/.opencode/commands/opsx-sync.md
@@ -0,0 +1,140 @@
+---
+description: Sync delta specs from a change to main specs
+---
+
+Sync delta specs from a change to main specs.
+
+This is an **agent-driven** operation - you will read delta specs and directly edit main specs to apply the changes. This allows intelligent merging (e.g., adding a scenario without copying the entire requirement).
+
+**Input**: Optionally specify a change name after `/opsx-sync` (e.g., `/opsx-sync 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 changes that have delta specs (under `specs/` directory).
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Resolve change context**
+
+   Run:
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+
+   If status reports `actionContext.mode: "workspace-planning"`, explain that workspace spec sync is not supported in this slice and STOP. Do not fall back to repo-local paths or edit linked repos.
+
+3. **Find delta specs**
+
+   Use `artifactPaths.specs.existingOutputPaths` from the status JSON as the list of delta spec files.
+
+   Each delta spec file contains sections like:
+   - `## ADDED Requirements` - New requirements to add
+   - `## MODIFIED Requirements` - Changes to existing requirements
+   - `## REMOVED Requirements` - Requirements to remove
+   - `## RENAMED Requirements` - Requirements to rename (FROM:/TO: format)
+
+   If no delta specs found, inform user and stop.
+
+4. **For each delta spec, apply changes to main specs**
+
+   For each repo-local capability delta spec path returned by the CLI:
+
+   a. **Read the delta spec** to understand the intended changes
+
+   b. **Read the main spec** at `openspec/specs/<capability>/spec.md` (may not exist yet)
+
+   c. **Apply changes intelligently**:
+
+      **ADDED Requirements:**
+      - If requirement doesn't exist in main spec → add it
+      - If requirement already exists → update it to match (treat as implicit MODIFIED)
+
+      **MODIFIED Requirements:**
+      - Find the requirement in main spec
+      - Apply the changes - this can be:
+        - Adding new scenarios (don't need to copy existing ones)
+        - Modifying existing scenarios
+        - Changing the requirement description
+      - Preserve scenarios/content not mentioned in the delta
+
+      **REMOVED Requirements:**
+      - Remove the entire requirement block from main spec
+
+      **RENAMED Requirements:**
+      - Find the FROM requirement, rename to TO
+
+   d. **Create new main spec** if capability doesn't exist yet:
+      - Create `openspec/specs/<capability>/spec.md`
+      - Add Purpose section (can be brief, mark as TBD)
+      - Add Requirements section with the ADDED requirements
+
+5. **Show summary**
+
+   After applying all changes, summarize:
+   - Which capabilities were updated
+   - What changes were made (requirements added/modified/removed/renamed)
+
+**Delta Spec Format Reference**
+
+```markdown
+## ADDED Requirements
+
+### Requirement: New Feature
+The system SHALL do something new.
+
+#### Scenario: Basic case
+- **WHEN** user does X
+- **THEN** system does Y
+
+## MODIFIED Requirements
+
+### Requirement: Existing Feature
+#### Scenario: New scenario to add
+- **WHEN** user does A
+- **THEN** system does B
+
+## REMOVED Requirements
+
+### Requirement: Deprecated Feature
+
+## RENAMED Requirements
+
+- FROM: `### Requirement: Old Name`
+- TO: `### Requirement: New Name`
+```
+
+**Key Principle: Intelligent Merging**
+
+Unlike programmatic merging, you can apply **partial updates**:
+- To add a scenario, just include that scenario under MODIFIED - don't copy existing scenarios
+- The delta represents *intent*, not a wholesale replacement
+- Use your judgment to merge changes sensibly
+
+**Output On Success**
+
+```
+## Specs Synced: <change-name>
+
+Updated main specs:
+
+**<capability-1>**:
+- Added requirement: "New Feature"
+- Modified requirement: "Existing Feature" (added 1 scenario)
+
+**<capability-2>**:
+- Created new spec file
+- Added requirement: "Another Feature"
+
+Main specs are now updated. The change remains active - archive when implementation is complete.
+```
+
+**Guardrails**
+- Read both delta and main specs before making changes
+- Preserve existing content not mentioned in delta
+- If something is unclear, ask for clarification
+- Show what you're changing as you go
+- The operation should be idempotent - running twice should give same result
diff --git a/.opencode/skills/openspec-apply-change/SKILL.md b/.opencode/skills/openspec-apply-change/SKILL.md
new file mode 100644
index 0000000..7bfb6c5
--- /dev/null
+++ b/.opencode/skills/openspec-apply-change/SKILL.md
@@ -0,0 +1,159 @@
+---
+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.4.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")
+   - `planningHome`, `changeRoot`, and `actionContext`: planning scope and edit constraints
+   - 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
+
+   **Workspace guard:** If status JSON reports `actionContext.mode: "workspace-planning"` and `allowedEditRoots` is empty, explain that full workspace apply is not supported in this slice. Treat linked repos and folders as read-only context, ask the user to select an affected area through an explicit implementation workflow, and STOP before editing files.
+
+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/.opencode/skills/openspec-archive-change/SKILL.md b/.opencode/skills/openspec-archive-change/SKILL.md
new file mode 100644
index 0000000..97c3e5e
--- /dev/null
+++ b/.opencode/skills/openspec-archive-change/SKILL.md
@@ -0,0 +1,117 @@
+---
+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.4.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
+   - `planningHome`, `changeRoot`, `artifactPaths`, and `actionContext`: path and scope context
+   - `artifacts`: List of artifacts with their status (`done` or other)
+
+   If status reports `actionContext.mode: "workspace-planning"`, explain that workspace archive is not supported in this slice and STOP. Do not move workspace changes into repo-local archives or edit linked repos.
+
+   **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**
+
+   Use `artifactPaths.specs.existingOutputPaths` from status JSON to check for delta 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 an `archive` directory under `planningHome.changesDir` if it doesn't exist:
+   ```bash
+   mkdir -p "<planningHome.changesDir>/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 `changeRoot` to the archive directory
+
+   ```bash
+   mv "<changeRoot>" "<planningHome.changesDir>/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:** the archive path derived from `planningHome.changesDir`/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/.opencode/skills/openspec-explore/SKILL.md b/.opencode/skills/openspec-explore/SKILL.md
new file mode 100644
index 0000000..a841906
--- /dev/null
+++ b/.opencode/skills/openspec-explore/SKILL.md
@@ -0,0 +1,287 @@
+---
+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.4.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. **Resolve and read existing artifacts for context**
+   - Run `openspec status --change "<name>" --json`.
+   - Use `changeRoot`, `artifactPaths`, and `actionContext` from the status JSON.
+   - Read existing files from `artifactPaths.<artifact>.existingOutputPaths`.
+
+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/.opencode/skills/openspec-propose/SKILL.md b/.opencode/skills/openspec-propose/SKILL.md
new file mode 100644
index 0000000..83b5557
--- /dev/null
+++ b/.opencode/skills/openspec-propose/SKILL.md
@@ -0,0 +1,111 @@
+---
+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.4.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 in the planning home resolved by the CLI 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
+   - `planningHome`, `changeRoot`, `artifactPaths`, and `actionContext`: path and scope context. Use these instead of assuming repo-local paths.
+
+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
+        - `resolvedOutputPath`: Resolved path or pattern 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 and write it to `resolvedOutputPath`
+      - 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/.opencode/skills/openspec-sync-specs/SKILL.md b/.opencode/skills/openspec-sync-specs/SKILL.md
new file mode 100644
index 0000000..e29bdd9
--- /dev/null
+++ b/.opencode/skills/openspec-sync-specs/SKILL.md
@@ -0,0 +1,147 @@
+---
+name: openspec-sync-specs
+description: Sync delta specs from a change to main specs. Use when the user wants to update main specs with changes from a delta spec, without archiving the change.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.4.1"
+---
+
+Sync delta specs from a change to main specs.
+
+This is an **agent-driven** operation - you will read delta specs and directly edit main specs to apply the changes. This allows intelligent merging (e.g., adding a scenario without copying the entire requirement).
+
+**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 changes that have delta specs (under `specs/` directory).
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Resolve change context**
+
+   Run:
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+
+   If status reports `actionContext.mode: "workspace-planning"`, explain that workspace spec sync is not supported in this slice and STOP. Do not fall back to repo-local paths or edit linked repos.
+
+3. **Find delta specs**
+
+   Use `artifactPaths.specs.existingOutputPaths` from the status JSON as the list of delta spec files.
+
+   Each delta spec file contains sections like:
+   - `## ADDED Requirements` - New requirements to add
+   - `## MODIFIED Requirements` - Changes to existing requirements
+   - `## REMOVED Requirements` - Requirements to remove
+   - `## RENAMED Requirements` - Requirements to rename (FROM:/TO: format)
+
+   If no delta specs found, inform user and stop.
+
+4. **For each delta spec, apply changes to main specs**
+
+   For each repo-local capability delta spec path returned by the CLI:
+
+   a. **Read the delta spec** to understand the intended changes
+
+   b. **Read the main spec** at `openspec/specs/<capability>/spec.md` (may not exist yet)
+
+   c. **Apply changes intelligently**:
+
+      **ADDED Requirements:**
+      - If requirement doesn't exist in main spec → add it
+      - If requirement already exists → update it to match (treat as implicit MODIFIED)
+
+      **MODIFIED Requirements:**
+      - Find the requirement in main spec
+      - Apply the changes - this can be:
+        - Adding new scenarios (don't need to copy existing ones)
+        - Modifying existing scenarios
+        - Changing the requirement description
+      - Preserve scenarios/content not mentioned in the delta
+
+      **REMOVED Requirements:**
+      - Remove the entire requirement block from main spec
+
+      **RENAMED Requirements:**
+      - Find the FROM requirement, rename to TO
+
+   d. **Create new main spec** if capability doesn't exist yet:
+      - Create `openspec/specs/<capability>/spec.md`
+      - Add Purpose section (can be brief, mark as TBD)
+      - Add Requirements section with the ADDED requirements
+
+5. **Show summary**
+
+   After applying all changes, summarize:
+   - Which capabilities were updated
+   - What changes were made (requirements added/modified/removed/renamed)
+
+**Delta Spec Format Reference**
+
+```markdown
+## ADDED Requirements
+
+### Requirement: New Feature
+The system SHALL do something new.
+
+#### Scenario: Basic case
+- **WHEN** user does X
+- **THEN** system does Y
+
+## MODIFIED Requirements
+
+### Requirement: Existing Feature
+#### Scenario: New scenario to add
+- **WHEN** user does A
+- **THEN** system does B
+
+## REMOVED Requirements
+
+### Requirement: Deprecated Feature
+
+## RENAMED Requirements
+
+- FROM: `### Requirement: Old Name`
+- TO: `### Requirement: New Name`
+```
+
+**Key Principle: Intelligent Merging**
+
+Unlike programmatic merging, you can apply **partial updates**:
+- To add a scenario, just include that scenario under MODIFIED - don't copy existing scenarios
+- The delta represents *intent*, not a wholesale replacement
+- Use your judgment to merge changes sensibly
+
+**Output On Success**
+
+```
+## Specs Synced: <change-name>
+
+Updated main specs:
+
+**<capability-1>**:
+- Added requirement: "New Feature"
+- Modified requirement: "Existing Feature" (added 1 scenario)
+
+**<capability-2>**:
+- Created new spec file
+- Added requirement: "Another Feature"
+
+Main specs are now updated. The change remains active - archive when implementation is complete.
+```
+
+**Guardrails**
+- Read both delta and main specs before making changes
+- Preserve existing content not mentioned in delta
+- If something is unclear, ask for clarification
+- Show what you're changing as you go
+- The operation should be idempotent - running twice should give same result
diff --git a/modules/home-manager/nvim/nvim/lazy-lock.json b/modules/home-manager/nvim/nvim/lazy-lock.json
index 6d3f9e5..ac9ebcf 100644
--- a/modules/home-manager/nvim/nvim/lazy-lock.json
+++ b/modules/home-manager/nvim/nvim/lazy-lock.json
@@ -1,6 +1,6 @@
 {
   "LuaSnip": { "branch": "master", "commit": "0abc8f390b278c3b4aabc4c004ac8a088b65cf24" },
-  "base16-nvim": { "branch": "master", "commit": "21233d5fd574439ae1e2f5e4bfbc574214f4ab3d" },
+  "base16-nvim": { "branch": "master", "commit": "012273e4bbf3e143224a272ad2efd10b69a000ba" },
   "catppuccin": { "branch": "main", "commit": "05e8787020dcfdb937bf2ff23855ea2415b4e072" },
   "cmp-buffer": { "branch": "main", "commit": "b74fab3656eea9de20a9b8116afa3cfc4ec09657" },
   "cmp-nvim-lsp": { "branch": "main", "commit": "cbc7b02bb99fae35cb42f514762b89b5126651ef" },
@@ -28,7 +28,7 @@
   "marks.nvim": { "branch": "master", "commit": "f353e8c08c50f39e99a9ed474172df7eddd89b72" },
   "mason.nvim": { "branch": "main", "commit": "2a6940af80375532e5e9e7c1f2fc6319a1b7a69d" },
   "mini.comment": { "branch": "main", "commit": "27a29d6b949b9497f80a0a03421e89fed71d8c37" },
-  "mini.nvim": { "branch": "main", "commit": "928971c3cfe99ddf29659acc31214cfa836fabe4" },
+  "mini.nvim": { "branch": "main", "commit": "db41c4076105a63caec12612d11228348f55a109" },
   "monochrome.nvim": { "branch": "main", "commit": "2de78d9688ea4a177bcd9be554ab9192337d35ff" },
   "monokai.nvim": { "branch": "master", "commit": "b8bd44d5796503173627d7a1fc51f77ec3a08a63" },
   "neo-tree.nvim": { "branch": "v3.x", "commit": "ebd66767191714e008ce73b769518a763ff31bdc" },
@@ -41,15 +41,16 @@
   "nord.nvim": { "branch": "master", "commit": "80c1e5321505aeb22b7a9f23eb82f1e193c12470" },
   "nui.nvim": { "branch": "main", "commit": "de740991c12411b663994b2860f1a4fd0937c130" },
   "nvim-autopairs": { "branch": "master", "commit": "7b9923abad60b903ece7c52940e1321d39eccc79" },
-  "nvim-cmp": { "branch": "main", "commit": "a1d504892f2bc56c2e79b65c6faded2fd21f3eca" },
-  "nvim-colorizer.lua": { "branch": "master", "commit": "664c0b7cea1de71f8b65dfe951b7996fc3e6ccde" },
+  "nvim-cmp": { "branch": "main", "commit": "2ffe79f1f021def8dd1fcd81deb16f1bb0d989f3" },
+  "nvim-colorizer.lua": { "branch": "master", "commit": "149fbd9f5e25511b0a8bad3ccecd43d1bc584f86" },
   "nvim-lsp-file-operations": { "branch": "master", "commit": "b9c795d3973e8eec22706af14959bc60c579e771" },
   "nvim-notify": { "branch": "master", "commit": "8701bece920b38ea289b457f902e2ad184131a5d" },
   "nvim-parinfer": { "branch": "master", "commit": "3968e669d9f02589aa311d33cb475b16b27c5fbb" },
   "nvim-silicon": { "branch": "main", "commit": "7f66bda8f60c97a5bf4b37e5b8acb0e829ae3c32" },
   "nvim-snazzy": { "branch": "main", "commit": "2d53dc44eac2e13cb205270cb534a500971d3ad5" },
   "nvim-treesitter": { "branch": "main", "commit": "4916d6592ede8c07973490d9322f187e07dfefac" },
-  "nvim-web-devicons": { "branch": "master", "commit": "dad71387de386a946b123079d0e53f23028f3abd" },
+  "nvim-web-devicons": { "branch": "master", "commit": "09d1324e264c6950262dbe02a9bce2933a6800db" },
+  "obsidian.nvim": { "branch": "main", "commit": "ae1f76a75c7ce36866e1d9342a8f6f5b9c2caf9b" },
   "oil.nvim": { "branch": "master", "commit": "b73018b75affd13fa38e2fc94ef753b465f770d7" },
   "plenary.nvim": { "branch": "master", "commit": "74b06c6c75e4eeb3108ec01852001636d85a932b" },
   "quicker.nvim": { "branch": "master", "commit": "4a6883cb13fe097a20a046eb55f6dffd239276e3" },
@@ -66,7 +67,5 @@
   "vim-markdown": { "branch": "master", "commit": "f9f845f28f4da33a7655accb22f4ad21f7d9fb66" },
   "vim-polyglot": { "branch": "master", "commit": "f061eddb7cdcc614c8406847b2bfb53099832a4e" },
   "vim-tmux-navigator": { "branch": "master", "commit": "e41c431a0c7b7388ae7ba341f01a0d217eb3a432" },
-  "vimwiki": { "branch": "dev", "commit": "a54a3002e229c4b43d69ced170ff77663a5b2c40" },
-  "which-key.nvim": { "branch": "main", "commit": "3aab2147e74890957785941f0c1ad87d0a44c15a" },
-  "zk": { "branch": "main", "commit": "bca7e4a119353f18f2a819385fb7ce10269ef747" }
+  "which-key.nvim": { "branch": "main", "commit": "3aab2147e74890957785941f0c1ad87d0a44c15a" }
 }
diff --git a/modules/home-manager/nvim/nvim/lua/jpporta/macros.lua b/modules/home-manager/nvim/nvim/lua/jpporta/macros.lua
index f73a580..fb8c9d8 100644
--- a/modules/home-manager/nvim/nvim/lua/jpporta/macros.lua
+++ b/modules/home-manager/nvim/nvim/lua/jpporta/macros.lua
@@ -1,4 +1,10 @@
 local esc = vim.api.nvim_replace_termcodes("<Esc>", true, true, true)
 local ret = vim.api.nvim_replace_termcodes("<CR>", true, true, true)
 
-vim.fn.setreg('o', "jjo�  - " ..esc.. "p4j0f:llv$hP3j0wv$hP" ..esc.. ":w" ..ret)
+vim.keymap.set("n", "<leader>op", function()
+	vim.api.nvim_feedkeys(esc .. "o" .. os.date("%H:%M", os.time()) .. ": ", "n", true)
+end, { expr = true, desc = "New atomic journal" })
+
+vim.keymap.set("i", "<C-p>", function()
+	vim.api.nvim_feedkeys(os.date("%H:%M", os.time()) .. ": ", "i", true)
+end, { desc = "New atomic journal inline" })
diff --git a/modules/home-manager/nvim/nvim/lua/plugin_bkp/obsidian.lua b/modules/home-manager/nvim/nvim/lua/plugins/obsidian.lua
similarity index 77%
rename from modules/home-manager/nvim/nvim/lua/plugin_bkp/obsidian.lua
rename to modules/home-manager/nvim/nvim/lua/plugins/obsidian.lua
index d1b68b6..8ef4475 100644
--- a/modules/home-manager/nvim/nvim/lua/plugin_bkp/obsidian.lua
+++ b/modules/home-manager/nvim/nvim/lua/plugins/obsidian.lua
@@ -57,20 +57,6 @@ return {
 				opts = { buffer = true },
 			},
 		},
-		templates = {
-			subdir = "Templates",
-			date_format = "%Y-%m-%d",
-			time_format = "%H:%M",
-			-- A map for custom variables, the key should be the variable and the value a function
-			substitutions = {
-				date_format = function()
-					return os.date("%Y-%m-%d")
-				end,
-				date_full = function()
-					return os.date("%B %-d, %Y")
-				end,
-			},
-		},
 		note_id_func = function(title)
 			local suffix = ""
 			if title ~= nil then
@@ -82,35 +68,19 @@ return {
 					suffix = suffix .. string.char(math.random(65, 90))
 				end
 			end
-			return os.date("%s", os.time())
-		end,
-		note_frontmatter_func = function(note)
-			-- This is equivalent to the default frontmatter function.
-			local out = {
-				tags = { "#note", "#journal" },
-				created = os.date("%Y-%m-%d %H:%M:%S"),
-			}
-			-- `note.metadata` contains any manually added fields in the frontmatter.
-			-- So here we just make sure those fields are kept in the frontmatter.
-			if note.metadata ~= nil and not vim.tbl_isempty(note.metadata) then
-				for k, v in pairs(note.metadata) do
-					out[k] = v
-				end
-			end
-			return out
+			return os.date("%s", os.time()) .. suffix
 		end,
 		follow_url_func = function(url)
-			-- vim.fn.jobstart({"xdg-open", url})  -- linux
 			vim.ui.open(url) -- need Neovim 0.10.0+
 		end,
 		-- Optional, configure additional syntax highlighting / extmarks.
 		ui = {
-			enable = true, -- set to false to disable all additional syntax features
+			enable = false, -- set to false to disable all additional syntax features
 			update_debounce = 200, -- update delay after a text change (in milliseconds)
 			-- Define how various check-boxes are displayed
 			checkboxes = {
 				-- NOTE: the 'char' value has to be a single character, and the highlight groups are defined below.
-				[" "] = { char = "", hl_group = "ObsidianTodo" },
+				[" "] = { char = " ", hl_group = "ObsidianTodo" },
 				["x"] = { char = "", hl_group = "ObsidianDone" },
 				[">"] = { char = "", hl_group = "ObsidianRightArrow" },
 				["<"] = { char = "", hl_group = "ObsidianLeftArrow" },
@@ -144,8 +114,45 @@ return {
 				ObsidianHighlightText = { bg = "#75662e" },
 			},
 		},
-		dir = "~/Documents/Notes",
-		new_notes_location = "notes_subdir",
+		--------------------------------
 		notes_subdir = "",
+		new_notes_location = "notes_subdir",
+		workspaces = {
+			{
+				name = "personal",
+				path = "~/docs/personal",
+			},
+		},
+		daily_notes = {
+			folder = "journal",
+			date_format = "%Y-%m-%d",
+			default_tags = { "journal" },
+			template = "journal"
+		},
+		completion = {
+			nvim_cmp = true,
+			min_chars = 2,
+		},
+
+		templates = {
+			subdir = "templates",
+			date_format = "%Y-%m-%d",
+			time_format = "%H:%M",
+		},
+		picker = {
+			name = "telescope.nvim",
+			note_mappings = {
+				-- Create a new note from your query.
+				new = "<C-x>",
+				-- Insert a link to the selected note.
+				insert_link = "<C-l>",
+			},
+			tag_mappings = {
+				-- Add tag(s) to current note.
+				tag_note = "<C-x>",
+				-- Insert a tag at the current location.
+				insert_tag = "<C-l>",
+			},
+		},
 	},
 }
diff --git a/modules/home-manager/nvim/nvim/lua/plugins/wiki.lua b/modules/home-manager/nvim/nvim/lua/plugins/wiki.lua
deleted file mode 100644
index c0fa3c8..0000000
--- a/modules/home-manager/nvim/nvim/lua/plugins/wiki.lua
+++ /dev/null
@@ -1,9 +0,0 @@
-return {
-	"vimwiki/vimwiki",
-	init = function()
-		vim.g.vimwiki_path = "~/docs/Wiki/"
-		vim.g.vimwiki_syntax = "markdown"
-		vim.g.vimwiki_ext = "md"
-		vim.g.vimwiki_global_ext = 0
-	end,
-}
diff --git a/modules/home-manager/nvim/nvim/lua/plugins/zk.lua b/modules/home-manager/nvim/nvim/lua/plugins/zk.lua
deleted file mode 100644
index 15035e2..0000000
--- a/modules/home-manager/nvim/nvim/lua/plugins/zk.lua
+++ /dev/null
@@ -1,25 +0,0 @@
-return {
-  "zk-org/zk-nvim",
-  name = "zk",
-  opts = {
-    -- Can be "telescope", "fzf", "fzf_lua", "minipick", "snacks_picker",
-    -- or select" (`vim.ui.select`).
-    picker = "select",
-
-    lsp = {
-      -- `config` is passed to `vim.lsp.start(config)`
-      config = {
-        name = "zk",
-        cmd = { "zk", "lsp" },
-        filetypes = { "markdown" },
-        -- on_attach = ...
-        -- etc, see `:h vim.lsp.start()`
-      },
-
-      -- automatically attach buffers in a zk notebook that match the given filetypes
-      auto_attach = {
-        enabled = true,
-      },
-    },
-  },
-}
diff --git a/modules/home-manager/tmux/tmux.conf b/modules/home-manager/tmux/tmux.conf
index 68adfd8..6ebb0da 100644
--- a/modules/home-manager/tmux/tmux.conf
+++ b/modules/home-manager/tmux/tmux.conf
@@ -10,7 +10,7 @@ set -g pane-active-border-style "bg=default"
 set -g status-style "bg=default"
 set -g window-style "bg=default"
 set -g window-active-style "bg=default"
-set -g default-shell /home/jpporta/.nix-profile/bin/zsh
+set -g default-shell zsh
 set -g extended-keys on
 set -g extended-keys-format csi-u
 
diff --git a/openspec/changes/archive/2026-07-13-theme-switch/.openspec.yaml b/openspec/changes/archive/2026-07-13-theme-switch/.openspec.yaml
new file mode 100644
index 0000000..b119b63
--- /dev/null
+++ b/openspec/changes/archive/2026-07-13-theme-switch/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-07-13
diff --git a/openspec/changes/archive/2026-07-13-theme-switch/design.md b/openspec/changes/archive/2026-07-13-theme-switch/design.md
new file mode 100644
index 0000000..13eacf3
--- /dev/null
+++ b/openspec/changes/archive/2026-07-13-theme-switch/design.md
@@ -0,0 +1,160 @@
+## Context
+
+The user runs jpporta-nixos (Hyprland on Wayland) and jpporta-deck (a OrangePi running cage + foot as a "writer deck"). They maintain 11 hand-curated palettes under `~/.config/colorschemes/<theme>/` with per-app config files (hyprland, waybar, swaync, wlogout, kitty, ghostty, nvim, rofi, gtk-4.0, plus a `wallpapers/` directory). Currently:
+
+- **Hyprland, awww, waybar, kitty, ghostty** are reachable from the themed dirs (with manual edits).
+- **swaync, wlogout, alacritty** have their colors hardcoded as Nix strings in `modules/home-manager/*/default.nix`, so swapping themes requires `home-manager switch`.
+- **darkman** runs a dark/light switch (geolocation-based) that flips GTK theme and hyprsunset temperature — its `gtk-theme` step overlaps with what theme-switch will own.
+- **No canonical "current theme" pointer** exists. The `~/.config/colorschemes/wallpapers` symlink is a one-off pointing at gruvbox-dark.
+- **No live propagation contract** — every themed app needs its own reload mechanism (file watch, IPC, signal, or restart-on-next-launch).
+
+The user wants: one command to swap themes, no rebuild, every themed app reflects the new palette, dark/light mode is owned by the theme (not by darkman), darkman keeps doing what it's good at (time-of-day temperature), and the writer deck can adopt the same workflow.
+
+Constraints discovered during exploration:
+
+- All per-theme assets must remain editable in `~/.config/colorschemes/<theme>/` without rebuild — this is the precedent set by the `awww` module (reads wallpaper dir live, never copies to store).
+- Theme colors live in dotfiles, not Nix. Anything baked into Nix is a second source of truth and must be removed.
+- The `.active` symlink pattern is preferred over a sentinel file because it's atomic (`ln -sfn`) and serves as the directory apps follow directly.
+- Darkman should keep its sunset/sunrise logic for `hyprsunset`, but stop touching GTK (theme owns that).
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Atomic theme swap with one shell command (`theme-switch <name>`) — no Nix rebuild, no per-app scripting by the user.
+- Single canonical pointer (`~/.config/colorschemes/.active` symlink) that every themed app can follow.
+- Per-app live reload: each app gets exactly the reload signal it natively supports, scripted in one place.
+- gsettings `color-scheme` flip driven by `meta` (theme declares its mode).
+- Hook point for user-owned wallpaper logic (`~/.config/colorschemes/.hook <theme-name>`), exec'd at the end of every switch.
+- Boot-time application: a systemd user oneshot re-applies `.current` on graphical-session start so login is consistent.
+- Rofi-driven picker (`theme-picker`) wired to a Hyprland keybind (`SUPER+T`).
+- Same module works on the writer deck; foot has no live reload but a relaunch in cage is fine.
+
+**Non-Goals:**
+
+- Generating palettes from images (this is what matugen/pywal do — user wants named curated palettes).
+- Per-app templating engines. Each app already has its own config format; we hand-write the swap for each.
+- Supporting themes that live outside `~/.config/colorschemes/`.
+- Backwards compatibility for the existing `~/.config/colorschemes/wallpapers` symlink (it becomes redundant once `.active/wallpapers/` exists; the script handles the migration).
+- Replacing darkman. darkman stays for `hyprsunset` time-of-day control.
+- Auto-detecting new themes. The `meta` file must exist per theme; the user adds them by hand.
+- Adding new external dependencies (no new packages).
+
+## Decisions
+
+### D1. `.active` symlink as the single source of truth, not a sentinel file
+
+**Choice:** `~/.config/colorschemes/.active` is a symlink pointing at the current theme's directory. A `.current` text file mirrors the name for tools that can't follow symlinks (some app loaders, the boot-time applier).
+
+**Why:** Atomic swap with one syscall (`ln -sfn`). Apps that support symlink-following read `~/.config/colorschemes/.active/<app>/` directly. Apps that need a name read `.current`. Both can coexist; the cost is two writes per switch.
+
+**Alternatives considered:**
+- *Plain `.current` text file only*: requires every app to maintain its own per-app link/symlink. Doesn't scale.
+- *Environment variable*: lost across reboots, hard to introspect from running processes, fights with systemd user services.
+- *dconf / gsettings schema*: forces every app into a GTK-ish world; waybar/kitty/ghostty/hyprland don't read it.
+
+### D2. Per-app reload handled inside `theme-switch`, not via inotify watchers
+
+**Choice:** `theme-switch` is the orchestrator. It runs each per-app reload step explicitly. No daemon watches `~/.config/colorschemes/.active` for changes.
+
+**Why:** Hyprland auto-watches its config (free). Other apps don't, and inventing an inotify daemon to *poke* apps adds a new failure surface. The user's stance: "if the app watches its own config, fine; otherwise, send the signal." That's exactly what `theme-switch` does.
+
+**Alternatives considered:**
+- *inotifywait daemon*: one more systemd service, one more race condition, no benefit over the explicit script.
+- *DBus signal + per-app subscribers*: significant scaffolding for what amounts to ~10 commands.
+
+### D3. Theme metadata via per-theme `meta` file, not Nix
+
+**Choice:** Each theme gets a one-line `~/.config/colorschemes/<theme>/meta` file with `name=Display Name` and `mode=dark|light` (KEY=value, simple parser).
+
+**Why:** Keeps the colorscheme dir fully self-describing. The `theme-picker` script reads these for its rofi menu. `theme-switch` reads the mode field to flip gsettings. No Nix expression, no rebuild.
+
+**Alternatives considered:**
+- *Filename convention (`gruvbox-dark/`, `e-ink-light/`) — infer mode from name*: fragile, requires a registry.
+- *First-line comment in `colors.conf`*: mixes concerns (colors.conf is for hyprland, not for metadata).
+
+### D4. Cleanup pass on swaync/wlogout/alacritty is required, not optional
+
+**Choice:** Remove the hardcoded gruvbox colors from the three Nix modules. They become thin wrappers that `xdg.configFile` the active theme dir via out-of-store symlinks (same pattern as the existing `nvim` module).
+
+**Why:** Without this, three of the user's themed apps simply won't switch (their colors are baked at build time). The cleanup is a one-time `home-manager switch`; theme switches thereafter are runtime only.
+
+**Alternatives considered:**
+- *Leave Nix modules alone, accept that swaync/wlogout/alacritty don't switch*: violates the user's goal of "every app picks up the new theme."
+- *Template them at activation time*: requires `home-manager switch` on every theme change — explicitly rejected.
+
+### D5. Darkman narrowed to hyprsunset only
+
+**Choice:** `darkman` stays enabled. Its scripts lose the `gtk-theme` step (theme-switch owns that now) and keep the `hyprsunset` step (time-of-day temperature). `theme-switch` does not poke darkman.
+
+**Why:** Theme owns *which palette* (dark vs light). Darkman owns *when to warm the screen* (sunset/sunrise). They're orthogonal and shouldn't fight. Conflating them — e.g., theme-switch telling darkman what mode to be in — creates two writers for the same gsettings keys.
+
+**Alternatives considered:**
+- *Theme-switch sets the darkman mode file*: simple but couples two systems that don't otherwise need to know about each other.
+- *Kill darkman*: loses the automatic sunset temperature shift, which the user said they want to keep.
+
+### D6. Wallpaper hook is user-owned, executed at end of switch
+
+**Choice:** If `~/.config/colorschemes/.hook` exists and is executable, `theme-switch` runs it as `~/.config/colorschemes/.hook <theme-name>` at the very end of the switch. If it doesn't exist, the switch still completes.
+
+**Why:** Wallpaper policy is personal (random pick? curated list? match a subdirectory?). The change shouldn't ship a wallpaper-rotation script the user didn't ask for. The hook is a single, documented extension point.
+
+**Alternatives considered:**
+- *Bundle a default random-wallpaper script in the Nix module*: scope creep, and the user explicitly said "you can leave that part to me."
+- *awww integration baked into theme-switch*: same as above; also, awww already has its own `awww-cycle` systemd timer that picks from `~/Wallpapers`, and the `wallpapers` symlink today points at the theme's dir — so all theme-switch needs to do is repoint the symlink.
+
+### D7. Boot-time re-apply via systemd user oneshot
+
+**Choice:** `theme-switch` (no args) is idempotent: it reads `.current` and re-applies. A `theme-apply.service` systemd user oneshot is `WantedBy=graphical-session.target` and runs it on session start.
+
+**Why:** Ensures the desktop matches `.current` after login even if a previous session crashed mid-switch. Cheap (the script no-ops if the symlink already points there).
+
+**Alternatives considered:**
+- *Home Manager activation hook*: runs only on `home-manager switch`, not on plain reboots.
+- *Hyprland autostart command*: works but mixes init logic into compositor config; systemd target is cleaner.
+
+### D8. Rofi picker is a thin wrapper, not a replacement for the CLI
+
+**Choice:** `theme-picker` is a small script that reads each theme's `meta`, pipes them through `rofi -dmenu`, and `exec`s `theme-switch` on the chosen name. The CLI is the source of truth; the picker is sugar.
+
+**Why:** Scriptability (cron, hyprland keybind action, shell aliases) belongs in the CLI. The picker is one Hyprland keybind away.
+
+**Alternatives considered:**
+- *Waybar module*: cute but adds a waybar dependency to a feature that doesn't need it.
+- *TUI (fzf, gum)*: extra dependency, no gain.
+
+### D9. Writer deck adopts the same script, with foot handled as "relaunch on switch"
+
+**Choice:** Same Nix module imports into `hosts/writter-deck/home.nix`. The `theme-switch` script on the deck has a foot-specific step: `pkill foot && foot --server &` (foot's server-mode makes this near-instant for a writer deck).
+
+**Why:** Zero new concepts on the deck. The user's deck is already gruvbox; this just lets them pick another.
+
+**Alternatives considered:**
+- *Separate `theme-switch-foot` script*: duplication for one app.
+- *Skip the deck*: explicit non-goal of the user — they want it if cheap.
+
+## Risks / Trade-offs
+
+- **Atomicity of multi-app reload** → Mitigation: order the steps so data lands before signals (`hyprland` config swap is just a file rewrite; signals come after). If one app fails mid-sequence, the user can re-run `theme-switch <name>` — it's idempotent.
+
+- **Hyprland's `source =` directive points at a path that must exist before hyprland reads it** → Mitigation: on first install, the activation script creates `.active` from `custom.theme.current` *before* hyprland starts. Hyprland only loads on graphical-session start (after `theme-apply.service`).
+
+- **Waybar `@import` and symlink interplay** → Mitigation: waybar's `style.css` will `@import` from `themes/current.css` (a symlink the script updates); SIGUSR2 forces re-eval.
+
+- **nvim running sessions won't recolor** → Mitigation: the script tries `nvim --remote-expr "colorscheme <name>"` if `$NVIM` is set; if not, only new nvim windows pick up the new theme. Documented as expected.
+
+- **alacritty has no live color reload** → Mitigation: next-launched alacritty instances pick up the new config; existing windows keep their colors until restarted. Documented. (This matches alacritty's own behavior; not a regression.)
+
+- **ghostty live reload is `SIGHUP`** → Mitigation: send `SIGHUP` to the running ghostty; on some versions this re-reads the config. If ghostty is unresponsive, the user restarts the terminal. Acceptable.
+
+- **First-time switch after the cleanup rebuild may visually flash old-then-new** → Mitigation: the boot-time oneshot re-applies `.current` *before* the user sees the desktop; the flash only happens if the user runs `theme-switch` interactively, which is the point.
+
+- **Adding a new theme requires writing a `meta` file** → Mitigation: documented in the theme module's option description. The `meta` file is two lines.
+
+- **`darkman`'s gsettings writes could fight `theme-switch`'s** → Mitigation: the cleanup pass removes darkman's `gtk-theme` script entirely. After this change, darkman writes only to `hyprsunset`. No overlap.
+
+- **Nix modules becoming "thin" can feel like over-abstraction to a reader who expects colors there** → Mitigation: the modules keep their `enable` options and any non-color config (font, opacity, layout). Only color strings leave. Comment in each module notes "colors come from `~/.config/colorschemes/.active/<app>/`."
+
+- **Hook script runs as the user with no sandboxing** → Mitigation: it lives in the user's home dir, owned by the user. This is the same trust level as a shell alias. Documented in `theme-switch`'s usage output.
+
+- **`ln -sfn` over an existing `.active` symlink is correct, but if `.active` exists as a *directory* (corruption), the symlink will be created inside it** → Mitigation: the script first checks `[ -L .active ] || [ ! -e .active ]` and bails with a clear error if `.active` is a directory. Documented in the script header.
diff --git a/openspec/changes/archive/2026-07-13-theme-switch/proposal.md b/openspec/changes/archive/2026-07-13-theme-switch/proposal.md
new file mode 100644
index 0000000..e8a4930
--- /dev/null
+++ b/openspec/changes/archive/2026-07-13-theme-switch/proposal.md
@@ -0,0 +1,50 @@
+## Why
+
+Today, switching color themes on jpporta-nixos requires manual editing of files scattered across `~/.config/`, plus a `nixos-rebuild switch` whenever a themed Nix module (swaync, wlogout) is involved. The user already maintains 11 curated palettes under `~/.config/colorschemes/<theme>/` (catppuccin, gruvbox-dark, tokyo-night, nord-darker, rose-pine, kanagawa, nightfox, everforest-dark, e-ink, noir, and one more), but there is no canonical "current theme" pointer, no atomic swap, no live propagation to running apps, and no keybind-driven picker. The user wants to switch themes in one command — fast, with no rebuild — and have every themed app update.
+
+## What Changes
+
+- **New module `modules/home-manager/theme/`** that installs `theme-switch` (CLI) and `theme-picker` (rofi wrapper) into `~/.local/bin`, adds a `SUPER+T` Hyprland keybind for the picker, declares `custom.theme.current` as the boot-time default, and registers a systemd user oneshot that re-applies the current theme on graphical-session start.
+- **New script `theme-switch <name>`** that performs an atomic theme swap by rewriting a single `~/.config/colorschemes/.active` symlink, then emits per-app reload signals (waybar SIGUSR2, swaync-client `--reload-css`, kitty `@ set-colors`, ghostty SIGUSR1, gsettings color-scheme flip, etc.) so live apps reflect the new palette without restart. Idempotent: invoked with no args, it re-applies whatever `.current` says (used on boot).
+- **New script `theme-picker`** — a rofi-driven wrapper around `theme-switch` that lists available themes from `~/.config/colorschemes/*/meta` and invokes the switcher on selection.
+- **New per-theme `meta` file** (one per theme): `name=...`, `mode=dark|light`. Drives gsettings and the darkman integration.
+- **Hook point `~/.config/colorschemes/.hook <theme-name>`**: `theme-switch` execs this at the end of every switch. This is where the user drops their wallpaper-rotation script. The change does NOT write the wallpaper hook — that is owned by the user.
+- **Cleanup pass** on `swaync`, `wlogout`, `alacritty`, and `darkman` Nix modules: drop the hardcoded gruvbox color strings (Nix store), point their configs at the active theme dir via out-of-store symlinks, and reduce `darkman` to only drive `hyprsunset` (time-of-day temperature). After this one-time rebuild, theme switching never touches Nix again.
+- **Bonus (writer-deck)**: same Nix module imported by `hosts/writter-deck/home.nix` so the foot terminal on the Steam Deck can switch themes the same way (foot has no live reload, but a relaunch in cage is acceptable for a writer deck).
+
+No app configuration is being deleted from `dotfiles/colorschemes/`; the cleanup pass only removes the *duplicate* hardcoded gruvbox strings that currently live in Nix modules while leaving the themed files in `~/.config/colorschemes/<theme>/` untouched.
+
+## Capabilities
+
+### New Capabilities
+
+- `theme-switch`: the runtime CLI + rofi picker + boot-time applier; defines the contract for what "switching themes" means in this system (atomic `.active` symlink, per-app reload signals, hook execution, gsettings flip driven by `meta` mode).
+- `theme-colors-sources`: the convention that every themed app on this system reads its colors from `~/.config/colorschemes/.active/<app>/...` rather than from Nix-store-baked strings; covers the cleanup pass on swaync/wlogout/alacritty so future theme additions don't require module edits.
+
+### Modified Capabilities
+
+<!-- No existing specs in openspec/specs/ yet, so nothing to list. The cleanup pass on swaync/wlogout/alacritty/darkman is implementation-level, not a requirement change for any existing spec. -->
+
+## Impact
+
+- **New files**:
+  - `modules/home-manager/theme/default.nix`
+  - `modules/home-manager/theme/theme-switch.sh` (script template embedded in Nix)
+  - `modules/home-manager/theme/theme-picker.sh` (script template embedded in Nix)
+  - `~/.config/colorschemes/.current` (runtime, owned by script)
+  - `~/.config/colorschemes/.active` (symlink, runtime)
+  - `~/.config/colorschemes/.hook` (user-owned, optional)
+  - `~/.config/colorschemes/<theme>/meta` (one per theme)
+- **Modified files**:
+  - `modules/home-manager/swaync/default.nix` — drop inline gruvbox, point at out-of-store config
+  - `modules/home-manager/wlogout/default.nix` — same
+  - `modules/home-manager/alacritty/default.nix` — add `import` for external colors file (font/opacity stay Nix)
+  - `modules/home-manager/darkman/default.nix` — remove `gtk-theme` scripts, keep `hyprsunset`
+  - `modules/home-manager/hyprland/default.nix` — add `SUPER+T` keybind for `theme-picker` (or document the user adding it)
+  - `hosts/jpporta-nixos/home.nix` — import new theme module
+  - `hosts/writter-deck/home.nix` — import new theme module (bonus)
+  - `~/.config/hypr/hyprland.conf` (or the lua-generated version) — point hyprland at `colorschemes/.active/hypr/colors.conf` via `source =`
+  - `~/.config/waybar/style.css` — switch from `@import "./themes/gruvbox-dark.css"` to `@import` from a symlinked `themes/current.css` (or equivalent)
+- **Affected apps** (live-reload behavior changes): swaync (CSS reload instead of restart), wlogout (next-invocation reload, no live signal), waybar (SIGUSR2), kitty (IPC), ghostty (SIGUSR1), alacritty (next-launch), nvim (new windows; optional remote-expr for running session), gtk-4 apps (gsettings flip).
+- **No new external dependencies**: rofi, swaync-client, kitty, ghostty, waybar, gsettings, notify-send (libnotify) are already installed.
+- **No breaking changes** for users not using the new command — existing gruvbox-dark setup continues to work; the first `theme-switch` after rebuild is a no-op if `.current` already matches.
\ No newline at end of file
diff --git a/openspec/changes/archive/2026-07-13-theme-switch/specs/theme-colors-sources/spec.md b/openspec/changes/archive/2026-07-13-theme-switch/specs/theme-colors-sources/spec.md
new file mode 100644
index 0000000..5c84e94
--- /dev/null
+++ b/openspec/changes/archive/2026-07-13-theme-switch/specs/theme-colors-sources/spec.md
@@ -0,0 +1,85 @@
+# Spec: theme-colors-sources
+
+## ADDED Requirements
+
+### Requirement: Swaync reads colors from the active theme dir, not from Nix
+
+The swaync Home Manager module SHALL NOT inline color strings. Instead, the module SHALL ensure that `~/.config/swaync/style.css` (and any related color file) is sourced from the active theme dir via an out-of-store symlink to `~/.config/colorschemes/.active/swaync/`.
+
+#### Scenario: swaync config is symlinked to active theme
+- **WHEN** the user has applied this change
+- **THEN** `~/.config/swaync/colors.css` resolves through `~/.config/colorschemes/.active/swaync/colors.css`
+- **AND** the swaync Nix module contains no color hex strings
+
+#### Scenario: Theme switch reflects in swaync without rebuild
+- **WHEN** the user runs `theme-switch catppuccin`
+- **THEN** swaync restyles via `swaync-client --reload-css` after the symlink swap
+- **AND** no `home-manager switch` is required
+
+### Requirement: Wlogout reads colors from the active theme dir, not from Nix
+
+The wlogout Home Manager module SHALL NOT inline color strings. Instead, the module SHALL ensure that `~/.config/wlogout/style.css` is sourced from the active theme dir via an out-of-store symlink to `~/.config/colorschemes/.active/wlogout/`.
+
+#### Scenario: wlogout config is symlinked to active theme
+- **WHEN** the user has applied this change
+- **THEN** `~/.config/wlogout/style.css` resolves through `~/.config/colorschemes/.active/wlogout/style.css`
+- **AND** the wlogout Nix module contains no color hex strings
+
+#### Scenario: Next wlogout invocation uses new colors
+- **WHEN** the user runs `theme-switch` and then invokes wlogout
+- **THEN** wlogout uses the new palette (no live reload required; wlogout reads its config at launch)
+
+### Requirement: Alacritty imports colors from an external file
+
+The alacritty Home Manager module SHALL configure alacritty to import colors from `~/.config/alacritty/colors.toml` (or equivalent), which is symlinked from the active theme dir.
+
+#### Scenario: alacritty config imports external colors file
+- **WHEN** the user has applied this change
+- **THEN** `~/.config/alacritty/alacritty.toml` contains an `import = [...]` directive that includes the colors file
+- **AND** `~/.config/alacritty/colors.toml` resolves through `~/.config/colorschemes/.active/alacritty/colors.toml`
+- **AND** the alacritty Nix module contains no color hex strings (font, opacity, padding remain in Nix)
+
+#### Scenario: Next alacritty launch uses new colors
+- **WHEN** the user runs `theme-switch` and then launches a new alacritty window
+- **THEN** the new window uses the new palette
+
+### Requirement: Darkman is narrowed to hyprsunset only
+
+The darkman Home Manager module SHALL retain its `hyprsunset` script (sunset/sunrise temperature) and SHALL NOT contain any `gtk-theme` script. Theme-driven dark/light preference is owned by `theme-switch` via gsettings, not by darkman.
+
+#### Scenario: darkman scripts contain no gtk-theme step
+- **WHEN** the user has applied this change
+- **THEN** `services.darkman.darkModeScripts` does not include a `gtk-theme` key
+- **AND** `services.darkman.lightModeScripts` does not include a `gtk-theme` key
+
+#### Scenario: darkman still drives hyprsunset
+- **WHEN** the time crosses the darkman sunset/sunrise boundary
+- **THEN** the `hyprsunset` script runs and adjusts temperature/gamma
+- **AND** gsettings `color-scheme` is NOT modified by darkman
+
+### Requirement: Hyprland sources its colors from the active theme dir
+
+The hyprland Home Manager module (or its user-facing config file) SHALL be configured so that hyprland's color directives come from a `source =` directive pointing at `~/.config/colorschemes/.active/hypr/colors.conf`. The Nix module SHALL NOT inline color hex strings for theme-affected values (active/inactive borders, etc.).
+
+#### Scenario: Hyprland config sources from active theme
+- **WHEN** the user has applied this change
+- **THEN** `~/.config/hypr/hyprland.conf` (or its lua-generated form) contains `source = ~/.config/colorschemes/.active/hypr/colors.conf`
+- **AND** the Hyprland module contains no inline color hex strings for theme-affected directives
+
+#### Scenario: Theme switch reflects in hyprland without rebuild
+- **WHEN** the user runs `theme-switch`
+- **THEN** hyprland automatically reloads its config (it watches the file)
+- **AND** no `home-manager switch` is required
+
+### Requirement: Every themed app reads from a single source of truth
+
+Every app whose colors are themed on this host SHALL read its palette from `~/.config/colorschemes/.active/<app>/...` (directly or via symlink). No themed app SHALL have its colors baked into a Nix-managed file.
+
+#### Scenario: Audit: no color hex strings in themed-app Nix modules
+- **WHEN** the user runs `rg -i '#[0-9a-f]{6}' modules/home-manager/{swaync,wlogout,alacritty,hyprland,darkman}` after applying this change
+- **THEN** the only matches are in non-theme-affected contexts (e.g., alacritty font color is fine; swaync/wlogout/hyprland theme colors are gone)
+
+#### Scenario: Adding a new theme requires no Nix change
+- **WHEN** the user creates a new `~/.config/colorschemes/<new-theme>/` directory with the same per-app subdirs as existing themes, plus a `meta` file
+- **THEN** `theme-switch <new-theme>` works without any `home-manager switch`
+- **AND** the new theme appears in the rofi picker on next invocation
\ No newline at end of file
diff --git a/openspec/changes/archive/2026-07-13-theme-switch/specs/theme-switch/spec.md b/openspec/changes/archive/2026-07-13-theme-switch/specs/theme-switch/spec.md
new file mode 100644
index 0000000..12e49f3
--- /dev/null
+++ b/openspec/changes/archive/2026-07-13-theme-switch/specs/theme-switch/spec.md
@@ -0,0 +1,155 @@
+# Spec: theme-switch
+
+## ADDED Requirements
+
+### Requirement: Atomic theme swap via a single canonical pointer
+
+The system SHALL provide a single shell command, `theme-switch <theme-name>`, that switches the active theme by atomically rewriting `~/.config/colorschemes/.active` (a symlink) to point at `~/.config/colorschemes/<theme-name>/`.
+
+#### Scenario: Successful switch to a valid theme
+- **WHEN** the user runs `theme-switch catppuccin` and `~/.config/colorschemes/catppuccin/` exists
+- **THEN** `~/.config/colorschemes/.active` is a symlink whose target resolves to `~/.config/colorschemes/catppuccin`
+- **AND** `~/.config/colorschemes/.current` contains the text `catppuccin`
+
+#### Scenario: Switch with an unknown theme name
+- **WHEN** the user runs `theme-switch does-not-exist` and the directory does not exist
+- **THEN** the command exits non-zero
+- **AND** prints a list of valid theme names to stderr
+- **AND** does not modify `.active` or `.current`
+
+#### Scenario: Re-applying the current theme is a no-op
+- **WHEN** the user runs `theme-switch` with no arguments
+- **THEN** the command reads `.current`
+- **AND** re-applies every per-app reload step (idempotent)
+
+### Requirement: Per-theme metadata drives picker and gsettings
+
+The system SHALL read each theme's mode (dark or light) and display name from a `meta` file at `~/.config/colorschemes/<theme>/meta`.
+
+#### Scenario: meta file format
+- **WHEN** the user runs `theme-switch` against any theme
+- **THEN** the script reads `<theme>/meta`
+- **AND** parses lines of the form `key=value`
+- **AND** uses `mode=dark` or `mode=light` to drive gsettings
+- **AND** uses `name=...` for the rofi picker label
+
+#### Scenario: Missing meta file defaults to dark
+- **WHEN** a theme directory has no `meta` file
+- **THEN** `theme-switch` treats the theme as `mode=dark`
+- **AND** uses the directory name as the display name
+- **AND** emits a warning to stderr
+
+### Requirement: Per-app live reload covers every themed app on jpporta-nixos
+
+`theme-switch` SHALL emit the appropriate reload signal for each themed app on the host, in an order that places file/data changes before signals.
+
+#### Scenario: Hyprland picks up new colors via file watch
+- **WHEN** `theme-switch` rewrites `~/.config/hypr/hyprland.conf` so that its `source =` directive points at `~/.config/colorschemes/.active/hypr/colors.conf`
+- **THEN** the running Hyprland instance reloads automatically (it watches its config file)
+
+#### Scenario: waybar picks up new colors via SIGUSR2
+- **WHEN** `theme-switch` swaps the waybar CSS symlink and the colors.css file under it
+- **THEN** the running waybar instance receives SIGUSR2
+- **AND** restyles with the new palette
+
+#### Scenario: swaync picks up new CSS via swaync-client
+- **WHEN** `theme-switch` swaps `~/.config/swaync/colors.css`
+- **THEN** the script invokes `swaync-client --reload-css`
+- **AND** swaync restyles without restart
+
+#### Scenario: kitty picks up new colors via IPC
+- **WHEN** `theme-switch` invokes `kitty @ set-colors --all ~/.config/colorschemes/.active/kitty/colors.conf`
+- **THEN** every running kitty window restyles without restart
+
+#### Scenario: ghostty picks up new colors via SIGHUP
+- **WHEN** `theme-switch` sends SIGHUP to the running ghostty process
+- **THEN** ghostty re-reads its config (including the colors block)
+
+#### Scenario: alacritty uses the new palette on next launch
+- **WHEN** `theme-switch` swaps the alacritty colors file that `alacritty.toml` imports
+- **THEN** running alacritty windows keep their current colors until restarted
+- **AND** any newly launched alacritty instance uses the new palette
+
+#### Scenario: nvim recolors in-session when $NVIM is set
+- **WHEN** `theme-switch` runs and the user has `$NVIM` set (a running nvim server)
+- **THEN** the script invokes `nvim --remote-expr 'lua vim.cmd.colorscheme("<name>")'`
+- **AND** the running nvim recolors immediately
+- **WHEN** `$NVIM` is not set
+- **THEN** the script takes no action for nvim
+- **AND** newly launched nvim instances pick up the theme from the symlinked config
+
+#### Scenario: GTK dark/light preference follows theme meta
+- **WHEN** `theme-switch` reads `mode=dark` from the new theme's meta
+- **THEN** the script invokes `gsettings set org.gnome.desktop.interface color-scheme prefer-dark`
+- **WHEN** `mode=light`
+- **THEN** the script invokes `gsettings set org.gnome.desktop.interface color-scheme prefer-light`
+
+### Requirement: Rofi-driven theme picker is a thin wrapper over theme-switch
+
+The system SHALL provide a `theme-picker` script that lists available themes (display name + mode) via `rofi -dmenu` and invokes `theme-switch` on the user's selection.
+
+#### Scenario: Picker shows all available themes
+- **WHEN** the user runs `theme-picker`
+- **THEN** rofi displays one entry per theme directory under `~/.config/colorschemes/`
+- **AND** each entry shows the display name from `meta` and a `(dark)` or `(light)` suffix
+
+#### Scenario: Picker invokes theme-switch on selection
+- **WHEN** the user selects an entry in rofi
+- **THEN** `theme-picker` invokes `theme-switch <selected-theme-name>`
+- **AND** exits with the same status code
+
+### Requirement: Boot-time re-apply guarantees a consistent desktop on login
+
+The system SHALL provide a systemd user oneshot service that runs `theme-switch` (no args) on graphical-session start, ensuring `.current` is applied before the user sees the desktop.
+
+#### Scenario: Service runs on graphical-session start
+- **WHEN** the user's graphical session (Hyprland on jpporta-nixos; cage on jpporta-deck) starts
+- **THEN** `theme-apply.service` runs `theme-switch`
+- **AND** the service has no effect if `.current` already matches the running state
+
+#### Scenario: Service does not run before graphical session
+- **WHEN** the user's session is not yet at graphical-session.target
+- **THEN** `theme-apply.service` is not started
+- **AND** waits for the target
+
+### Requirement: Wallpaper hook is user-owned and exec'd at end of switch
+
+`theme-switch` SHALL execute `~/.config/colorschemes/.hook <theme-name>` at the end of every successful switch if that file exists and is executable.
+
+#### Scenario: Hook is invoked after all app reloads
+- **WHEN** `theme-switch` finishes the per-app reload block
+- **AND** `~/.config/colorschemes/.hook` exists and is executable
+- **THEN** the script executes `~/.config/colorschemes/.hook <theme-name>`
+- **AND** any non-zero exit status is logged but does not fail the switch
+
+#### Scenario: Missing hook does not fail the switch
+- **WHEN** `~/.config/colorschemes/.hook` does not exist or is not executable
+- **THEN** the switch still completes successfully
+
+### Requirement: Writer-deck adopts the same mechanism with foot handled at switch time
+
+The same `theme-switch` script SHALL work on jpporta-deck (cage + foot). Foot has no live color reload, so the deck profile SHALL include a foot-specific step that sends `SIGUSR1` (footserver reload) or, as a fallback, restarts the foot server.
+
+#### Scenario: Foot recolors via SIGUSR1 to footserver
+- **WHEN** `theme-switch` runs on jpporta-deck
+- **THEN** the script sends `SIGUSR1` to the footserver process if running
+- **AND** foot reloads its config without losing the running instance
+
+#### Scenario: footserver not running
+- **WHEN** `theme-switch` runs on jpporta-deck and no footserver is running
+- **THEN** the script takes no action for foot
+- **AND** the next foot launch picks up the new theme
+
+### Requirement: First-install migration creates .active from custom.theme.current
+
+On a fresh `home-manager switch` after this change is applied, the theme module SHALL ensure `~/.config/colorschemes/.active` exists and points at the theme named in `custom.theme.current`.
+
+#### Scenario: First install with default theme
+- **WHEN** the user applies this change for the first time and `custom.theme.current = "gruvbox-dark"`
+- **THEN** the activation creates `~/.config/colorschemes/.active` as a symlink to `~/.config/colorschemes/gruvbox-dark/`
+- **AND** writes `gruvbox-dark` to `~/.config/colorschemes/.current`
+
+#### Scenario: Existing wallpapers symlink is left in place during migration
+- **WHEN** `~/.config/colorschemes/wallpapers` is already a symlink (legacy)
+- **THEN** the migration does not remove it
+- **AND** documents in a comment that it is now redundant
\ No newline at end of file
diff --git a/openspec/changes/archive/2026-07-13-theme-switch/tasks.md b/openspec/changes/archive/2026-07-13-theme-switch/tasks.md
new file mode 100644
index 0000000..375da19
--- /dev/null
+++ b/openspec/changes/archive/2026-07-13-theme-switch/tasks.md
@@ -0,0 +1,91 @@
+# Tasks: theme-switch
+
+## 1. Per-theme metadata
+
+- [ ] 1.1 Create `~/.config/colorschemes/<theme>/meta` for each of the 11 existing themes with `name=<Display Name>` and `mode=dark` (or `mode=light` for `e-ink` and `noir`).
+
+## 2. Theme module scaffold
+
+- [ ] 2.1 Create `modules/home-manager/theme/default.nix` declaring `options.custom.theme.current` (string, default `"gruvbox-dark"`) and `options.custom.theme.enable` (bool).
+- [ ] 2.2 Embed the `theme-switch` shell script in the module via `pkgs.writeShellScriptBin` so it's installed to `~/.local/bin/theme-switch`.
+- [ ] 2.3 Embed the `theme-picker` shell script in the module via `pkgs.writeShellScriptBin` so it's installed to `~/.local/bin/theme-picker`.
+- [ ] 2.4 Add a systemd user oneshot `theme-apply.service` that runs `theme-switch` (no args) on `graphical-session.target`.
+- [ ] 2.5 Add a `home.activation` block that creates `~/.config/colorschemes/.active` (symlink to `custom.theme.current`) and `.current` (text file with the name) if missing.
+
+## 3. theme-switch script
+
+- [ ] 3.1 Implement argument parsing: `<theme-name>` switches; no args reads `.current` and re-applies.
+- [ ] 3.2 Validate `<theme-name>` exists under `~/.config/colorschemes/`; print list and exit non-zero otherwise.
+- [ ] 3.3 Refuse to proceed if `~/.config/colorschemes/.active` is a non-symlink directory (defensive guard).
+- [ ] 3.4 Atomically swap `.active` with `ln -sfn`.
+- [ ] 3.5 Write `<theme-name>` to `~/.config/colorschemes/.current`.
+- [ ] 3.6 Parse the new theme's `meta` for `name=` and `mode=`.
+- [ ] 3.7 Emit `gsettings set org.gnome.desktop.interface color-scheme prefer-{dark,light}` based on `mode=`.
+- [ ] 3.8 Update hyprland config: rewrite `~/.config/hypr/hyprland.conf` so its `source =` directive points at `~/.config/colorschemes/.active/hypr/colors.conf`. No signal (hyprland watches).
+- [ ] 3.9 Update waybar: atomic symlink swap for `~/.config/waybar/themes/current.css` → `<theme>/waybar/colors.css`, then `pkill -USR2 waybar`.
+- [ ] 3.10 Update swaync: atomic swap for `~/.config/swaync/colors.css` → `<theme>/swaync/colors.css`, then `swaync-client --reload-css`.
+- [ ] 3.11 Update wlogout: atomic swap for `~/.config/wlogout/style.css` → `<theme>/wlogout/style.css`. No live signal (next-launch reload).
+- [ ] 3.12 Update kitty: `kitty @ set-colors --all ~/.config/colorschemes/.active/kitty/colors.conf`.
+- [ ] 3.13 Update ghostty: `pkill -SIGUSR1 ghostty`.
+- [ ] 3.14 Update alacritty: atomic swap for `~/.config/alacritty/colors.toml` → `<theme>/alacritty/colors.toml`. No live signal (next-launch reload).
+- [ ] 3.15 Update nvim: if `$NVIM` is set, `nvim --remote-expr 'lua vim.cmd.colorscheme("<name>")'`. Else no-op.
+- [ ] 3.16 If `~/.config/colorschemes/.hook` exists and is executable, run `~/.config/colorschemes/.hook <theme-name>` at the end. Tolerate non-zero exit.
+- [ ] 3.17 Notify via `notify-send "Theme: <name>"` if libnotify is available.
+
+## 4. theme-picker script
+
+- [ ] 4.1 List `~/.config/colorschemes/*/meta` files.
+- [ ] 4.2 Parse each `meta` for `name=` and `mode=`.
+- [ ] 4.3 Pipe the formatted entries (`<name> (<mode>)`) into `rofi -dmenu -p "Theme"`.
+- [ ] 4.4 On selection, invoke `theme-switch <selected-theme-name>` and exit with its status.
+
+## 5. Cleanup pass: swaync
+
+- [ ] 5.1 Strip the inline gruvbox color strings from `modules/home-manager/swaync/default.nix` (the `let` block at the top with `background`, `text`, etc.).
+- [ ] 5.2 Replace the `style = ''...''` block with `xdg.configFile."swaync/style.css".source = config.lib.file.mkOutOfStoreSymlink "${config.home.homeDirectory}/.config/swaync/style.css"` (so the file lives in dotfiles and is theme-driven).
+- [ ] 5.3 Verify `~/.config/colorschemes/<theme>/swaync/colors.css` exists for all 11 themes; if any are missing, copy from `gruvbox-dark/swaync/colors.css` as a placeholder.
+
+## 6. Cleanup pass: wlogout
+
+- [ ] 6.1 Strip the inline gruvbox color strings from `modules/home-manager/wlogout/default.nix`.
+- [ ] 6.2 Replace the `style = ''...''` block with `xdg.configFile."wlogout/style.css".source = config.lib.file.mkOutOfStoreSymlink ...`.
+- [ ] 6.3 Verify `~/.config/colorschemes/<theme>/wlogout/colors.css` exists for all 11 themes.
+
+## 7. Cleanup pass: alacritty
+
+- [ ] 7.1 Keep font, opacity, padding, blur in `modules/home-manager/alacritty/default.nix`.
+- [ ] 7.2 Add `import = [ "~/.config/alacritty/colors.toml" ]` to `programs.alacritty.settings`.
+- [ ] 7.3 Ensure `~/.config/colorschemes/<theme>/alacritty/colors.toml` exists for all 11 themes (or document a one-time port if the existing files are in a different format).
+- [ ] 7.4 Add `xdg.configFile."alacritty/colors.toml".source = out-of-store symlink to ~/.config/colorschemes/.active/alacritty/colors.toml` (or document leaving it as a mutable file the script swaps).
+
+## 8. Cleanup pass: darkman
+
+- [ ] 8.1 Remove the `gtk-theme` key from both `services.darkman.darkModeScripts` and `services.darkman.lightModeScripts`.
+- [ ] 8.2 Leave the `hyprsunset` key in both modes (still time-of-day driven).
+- [ ] 8.3 Add a comment in the module noting that gsettings `color-scheme` is now owned by `theme-switch`.
+
+## 9. Hyprland integration
+
+- [ ] 9.1 In `modules/home-manager/hyprland/default.nix` (or the lua config it writes), ensure `~/.config/hypr/hyprland.conf` `source`s `~/.config/colorschemes/.active/hypr/colors.conf`.
+- [ ] 9.2 Strip inline color hex strings (active/inactive border) from the lua config.
+- [ ] 9.3 Add the `SUPER+T` keybind to launch `theme-picker` (in the `hl.bind` block).
+
+## 10. Wire into hosts
+
+- [ ] 10.1 Add `../../modules/home-manager/theme` to `imports` in `hosts/jpporta-nixos/home.nix`.
+- [ ] 10.2 Set `custom.theme.current = "gruvbox-dark";` (or another default) in the same file.
+- [ ] 10.3 (Bonus, deck) Add `../../modules/home-manager/theme` to `imports` in `hosts/writter-deck/home.nix` and set `custom.theme.current`.
+- [ ] 10.4 (Bonus, deck) Add a footserver-specific step to `theme-switch` that sends SIGUSR1 to the running footserver, or skips if none.
+
+## 11. Verification
+
+- [ ] 11.1 `home-manager switch` succeeds with no errors after all module changes.
+- [ ] 11.2 `~/.config/colorschemes/.active` exists and resolves to the configured theme on first boot.
+- [ ] 11.3 `theme-switch catppuccin` (or any other valid theme) swaps `.active`, updates `.current`, and emits each per-app reload signal.
+- [ ] 11.4 Each themed app reflects the new palette within ~2 seconds (manual eyeball test).
+- [ ] 11.5 `theme-switch does-not-exist` prints the list of valid themes and exits non-zero without modifying `.active`.
+- [ ] 11.6 `theme-picker` opens rofi, lists all 11 themes with their mode suffix, and switches on selection.
+- [ ] 11.7 `SUPER+T` in Hyprland opens the rofi picker.
+- [ ] 11.8 After a logout/login, the desktop matches `.current` (the systemd oneshot ran).
+- [ ] 11.9 Drop a placeholder `~/.config/colorschemes/.hook` that logs the theme name; verify it runs after a switch.
+- [ ] 11.10 (Deck, if wired) `theme-switch` works on the deck and footserver reloads colors (or relaunches).
\ No newline at end of file
diff --git a/openspec/config.yaml b/openspec/config.yaml
new file mode 100644
index 0000000..621f351
--- /dev/null
+++ b/openspec/config.yaml
@@ -0,0 +1,4 @@
+schema: spec-driven
+
+  context: |
+    Tech stack: Unix System, NixOS, Flakes, Home-manager