From 0fa2d10f40b08dc63d1f94ee99e9a07c14d76524 Mon Sep 17 00:00:00 2001
From: postlog <scarfaceborn@mail.ru>
Date: Sun, 28 Jun 2026 17:15:59 +0300
Subject: [PATCH] docs: migrate the change process to OpenSpec

Adopt OpenSpec (the spec-driven schema) as the planning and change-documentation
process, replacing the ADR catalog (the CHANGELOG stays). Seed a full spec baseline
under openspec/specs/ (12 capabilities, validated by `openspec validate --specs
--strict`), add the /opsx:* workflow under .claude/ (narrow the blanket .claude
gitignore to settings.local.json so the commands/skills are tracked), and rewrite
the process in AGENTS.md / CONTRIBUTING.md / README.md. Remove the docs/decisions/
ADR catalog (kept in git history); the migration's own rationale lives in the
archived change openspec/changes/archive/2026-06-28-adopt-openspec/.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .claude/commands/opsx/apply.md                | 155 ++++++++++
 .claude/commands/opsx/archive.md              | 160 ++++++++++
 .claude/commands/opsx/explore.md              | 174 +++++++++++
 .claude/commands/opsx/propose.md              | 109 +++++++
 .claude/commands/opsx/sync.md                 | 143 +++++++++
 .claude/skills/openspec-apply-change/SKILL.md | 159 ++++++++++
 .../skills/openspec-archive-change/SKILL.md   | 117 +++++++
 .claude/skills/openspec-explore/SKILL.md      | 289 ++++++++++++++++++
 .claude/skills/openspec-propose/SKILL.md      | 113 +++++++
 .claude/skills/openspec-sync-specs/SKILL.md   | 147 +++++++++
 .gitignore                                    |   3 +-
 AGENTS.md                                     |  49 +--
 CHANGELOG.md                                  |  33 +-
 CONTRIBUTING.md                               |  24 +-
 README.md                                     |   3 +-
 apitest/auth/login_test.go                    |   2 +-
 apitest/users/create_test.go                  |   2 +-
 apitest/users/edit_test.go                    |   3 +-
 docs/decisions/0000-template.md               |  24 --
 .../decisions/0001-adopt-changelog-and-adr.md |  43 ---
 .../0002-ordered-migration-runner.md          |  66 ----
 docs/decisions/0003-validation-in-code.md     |  68 -----
 .../0004-optional-user-description.md         |  58 ----
 docs/decisions/0005-strict-mihomo-refs.md     |  86 ------
 .../decisions/0006-recursive-routing-rules.md | 111 -------
 .../0008-subscription-link-catalog.md         |  58 ----
 .../0009-public-ready-and-english-docs.md     |  55 ----
 internal/entity/validation_errors.go          |   2 +-
 openspec/changes/.gitkeep                     |   1 +
 openspec/changes/archive/.gitkeep             |   1 +
 .../2026-06-28-adopt-openspec/design.md       |  49 +++
 .../2026-06-28-adopt-openspec/proposal.md     |  32 ++
 .../2026-06-28-adopt-openspec/tasks.md        |  13 +
 openspec/config.yaml                          |  60 ++++
 openspec/specs/admin-auth/spec.md             | 119 ++++++++
 openspec/specs/admin-users/spec.md            | 133 ++++++++
 openspec/specs/config-ownership/spec.md       |  65 ++++
 openspec/specs/database-migrations/spec.md    |  62 ++++
 openspec/specs/fleet/spec.md                  |  72 +++++
 openspec/specs/mihomo-config/spec.md          | 157 ++++++++++
 openspec/specs/mihomo-rendering/spec.md       |  64 ++++
 openspec/specs/nodes/spec.md                  |  76 +++++
 openspec/specs/platform/spec.md               |  34 +++
 openspec/specs/rule-provider-mirror/spec.md   |  49 +++
 openspec/specs/subscription-delivery/spec.md  |  74 +++++
 openspec/specs/user-provisioning/spec.md      |  75 +++++
 46 files changed, 2776 insertions(+), 616 deletions(-)
 create mode 100644 .claude/commands/opsx/apply.md
 create mode 100644 .claude/commands/opsx/archive.md
 create mode 100644 .claude/commands/opsx/explore.md
 create mode 100644 .claude/commands/opsx/propose.md
 create mode 100644 .claude/commands/opsx/sync.md
 create mode 100644 .claude/skills/openspec-apply-change/SKILL.md
 create mode 100644 .claude/skills/openspec-archive-change/SKILL.md
 create mode 100644 .claude/skills/openspec-explore/SKILL.md
 create mode 100644 .claude/skills/openspec-propose/SKILL.md
 create mode 100644 .claude/skills/openspec-sync-specs/SKILL.md
 delete mode 100644 docs/decisions/0000-template.md
 delete mode 100644 docs/decisions/0001-adopt-changelog-and-adr.md
 delete mode 100644 docs/decisions/0002-ordered-migration-runner.md
 delete mode 100644 docs/decisions/0003-validation-in-code.md
 delete mode 100644 docs/decisions/0004-optional-user-description.md
 delete mode 100644 docs/decisions/0005-strict-mihomo-refs.md
 delete mode 100644 docs/decisions/0006-recursive-routing-rules.md
 delete mode 100644 docs/decisions/0008-subscription-link-catalog.md
 delete mode 100644 docs/decisions/0009-public-ready-and-english-docs.md
 create mode 100644 openspec/changes/.gitkeep
 create mode 100644 openspec/changes/archive/.gitkeep
 create mode 100644 openspec/changes/archive/2026-06-28-adopt-openspec/design.md
 create mode 100644 openspec/changes/archive/2026-06-28-adopt-openspec/proposal.md
 create mode 100644 openspec/changes/archive/2026-06-28-adopt-openspec/tasks.md
 create mode 100644 openspec/config.yaml
 create mode 100644 openspec/specs/admin-auth/spec.md
 create mode 100644 openspec/specs/admin-users/spec.md
 create mode 100644 openspec/specs/config-ownership/spec.md
 create mode 100644 openspec/specs/database-migrations/spec.md
 create mode 100644 openspec/specs/fleet/spec.md
 create mode 100644 openspec/specs/mihomo-config/spec.md
 create mode 100644 openspec/specs/mihomo-rendering/spec.md
 create mode 100644 openspec/specs/nodes/spec.md
 create mode 100644 openspec/specs/platform/spec.md
 create mode 100644 openspec/specs/rule-provider-mirror/spec.md
 create mode 100644 openspec/specs/subscription-delivery/spec.md
 create mode 100644 openspec/specs/user-provisioning/spec.md

diff --git a/.claude/commands/opsx/apply.md b/.claude/commands/opsx/apply.md
new file mode 100644
index 0000000..f540757
--- /dev/null
+++ b/.claude/commands/opsx/apply.md
@@ -0,0 +1,155 @@
+---
+name: "OPSX: Apply"
+description: Implement tasks from an OpenSpec change (Experimental)
+category: Workflow
+tags: [workflow, artifacts, experimental]
+---
+
+Implement tasks from an OpenSpec change.
+
+**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store <id>` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`). Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root.
+
+**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
+
+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/.claude/commands/opsx/archive.md b/.claude/commands/opsx/archive.md
new file mode 100644
index 0000000..c895231
--- /dev/null
+++ b/.claude/commands/opsx/archive.md
@@ -0,0 +1,160 @@
+---
+name: "OPSX: Archive"
+description: Archive a completed change in the experimental workflow
+category: Workflow
+tags: [workflow, archive, experimental]
+---
+
+Archive a completed change in the experimental workflow.
+
+**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store <id>` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`). Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root.
+
+**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 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/.claude/commands/opsx/explore.md b/.claude/commands/opsx/explore.md
new file mode 100644
index 0000000..95bd0c8
--- /dev/null
+++ b/.claude/commands/opsx/explore.md
@@ -0,0 +1,174 @@
+---
+name: "OPSX: Explore"
+description: "Enter explore mode - think through ideas, investigate problems, clarify requirements"
+category: Workflow
+tags: [workflow, explore, experimental, thinking]
+---
+
+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.
+
+**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store <id>` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`). Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root.
+
+**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/.claude/commands/opsx/propose.md b/.claude/commands/opsx/propose.md
new file mode 100644
index 0000000..48152de
--- /dev/null
+++ b/.claude/commands/opsx/propose.md
@@ -0,0 +1,109 @@
+---
+name: "OPSX: Propose"
+description: Propose a new change - create it and generate all artifacts in one step
+category: Workflow
+tags: [workflow, artifacts, experimental]
+---
+
+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
+
+---
+
+**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store <id>` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`). Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root.
+
+**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/.claude/commands/opsx/sync.md b/.claude/commands/opsx/sync.md
new file mode 100644
index 0000000..277330c
--- /dev/null
+++ b/.claude/commands/opsx/sync.md
@@ -0,0 +1,143 @@
+---
+name: "OPSX: Sync"
+description: Sync delta specs from a change to main specs
+category: Workflow
+tags: [workflow, specs, experimental]
+---
+
+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).
+
+**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store <id>` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`). Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root.
+
+**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
+   ```
+
+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/.claude/skills/openspec-apply-change/SKILL.md b/.claude/skills/openspec-apply-change/SKILL.md
new file mode 100644
index 0000000..0573792
--- /dev/null
+++ b/.claude/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.5.0"
+---
+
+Implement tasks from an OpenSpec change.
+
+**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store <id>` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`). Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root.
+
+**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
+
+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/.claude/skills/openspec-archive-change/SKILL.md b/.claude/skills/openspec-archive-change/SKILL.md
new file mode 100644
index 0000000..bb6a8cf
--- /dev/null
+++ b/.claude/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.5.0"
+---
+
+Archive a completed change in the experimental workflow.
+
+**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store <id>` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`). Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root.
+
+**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 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/.claude/skills/openspec-explore/SKILL.md b/.claude/skills/openspec-explore/SKILL.md
new file mode 100644
index 0000000..756b31c
--- /dev/null
+++ b/.claude/skills/openspec-explore/SKILL.md
@@ -0,0 +1,289 @@
+---
+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.5.0"
+---
+
+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.
+
+**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store <id>` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`). Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root.
+
+---
+
+## 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/.claude/skills/openspec-propose/SKILL.md b/.claude/skills/openspec-propose/SKILL.md
new file mode 100644
index 0000000..0208e03
--- /dev/null
+++ b/.claude/skills/openspec-propose/SKILL.md
@@ -0,0 +1,113 @@
+---
+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.5.0"
+---
+
+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
+
+---
+
+**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store <id>` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`). Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root.
+
+**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/.claude/skills/openspec-sync-specs/SKILL.md b/.claude/skills/openspec-sync-specs/SKILL.md
new file mode 100644
index 0000000..f4ec054
--- /dev/null
+++ b/.claude/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.5.0"
+---
+
+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).
+
+**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store <id>` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`). Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root.
+
+**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
+   ```
+
+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/.gitignore b/.gitignore
index 1ec37fb..8b4265c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -6,7 +6,8 @@
 # Secrets — .env lives here; .env.example stays tracked
 *.env
 
-.claude
+# Claude Code — local-only settings stay out; shared commands/skills are tracked
+.claude/settings.local.json
 
 # Rendered per-client configs contain real UUIDs/keys — never commit
 examples/*.local.yaml
diff --git a/AGENTS.md b/AGENTS.md
index c756fdf..6d718a3 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -30,8 +30,7 @@ comments, log/error messages, user-facing strings and the admin UI, the docs (`R
 `AGENTS.md`, `docs/`, ADRs), the `CHANGELOG`, commit messages, and **pull-request titles and
 descriptions**. Non-English text (e.g. Cyrillic) must not appear anywhere in the tree — the
 only exception is operator-entered data that lives in the running store, not in the repo.
-Quick guard: `grep -rI '[А-Яа-я]'` over the tree comes back empty. See
-[ADR-0009](docs/decisions/0009-public-ready-and-english-docs.md).
+Quick guard: `grep -rI '[А-Яа-я]'` over the tree comes back empty.
 
 Structure references (look at as a model):
 `go.avito.ru/av/service-listing-admin`, `go.avito.ru/av/service-mnz-sf`.
@@ -94,7 +93,7 @@ RAM-starved — Go/registry are not needed on the node), shipped over SSH (`dock
 `README.md` / `docs/subgen.md`. The legacy systemd deploy has been removed (it was `systemd/`). There is no SIGHUP reload —
 the config flows bottom-up from the store on every request. **DB migrations — an ordered runner
 on start** (`migrations.Apply`: the `0001-init.sql` baseline + `NNNN-*.sql` by name, tracked in
-`schema_migrations`; see [ADR-0002](docs/decisions/0002-ordered-migration-runner.md)).
+`schema_migrations`).
 
 ## Target rules (layer inversion)
 
@@ -208,8 +207,7 @@ these formulations take priority. Any new code follows them; if you touch old co
   thin — it maps the sentinel into a typed 4xx with a local text constant. No service —
   we create one (`internal/service/nodes` owns node validation). **Surrogate ids (PK) we do not
   validate** — a non-existent id (whether negative or valid-but-absent)
-  yields not-found either way, a separate `id≥1` check is meaningless. See
-  [ADR-0003](docs/decisions/0003-validation-in-code.md).
+  yields not-found either way, a separate `id≥1` check is meaningless.
 - A handler's dependency — a concrete interface for the data it needs.
   **The anti-pattern `cfgReader{ Cfg() *config.Config }` is forbidden** — if you need a concrete field,
   pass the concrete field.
@@ -379,8 +377,7 @@ edit of the baseline (otherwise it diverges from already-adopted bases), not in-
 (`journal_mode=WAL`, `foreign_keys`, `busy_timeout`) live in the DSN (`open.go`), since `PRAGMA
 journal_mode` cannot be executed inside the runner's transaction. There are no rollbacks (forward-only). If
 a migration rebuilds a table via RENAME — set `PRAGMA legacy_alter_table=ON` before the
-RENAME (otherwise SQLite rewrites FKs in other tables and leaves dangling references). See
-[ADR-0002](docs/decisions/0002-ordered-migration-runner.md).
+RENAME (otherwise SQLite rewrites FKs in other tables and leaves dangling references).
 
 ## Dependencies: `contract.go` + mockgen
 
@@ -541,24 +538,34 @@ parallel work, and makes branch → commit → push → PR the only path into `m
   apitest) and confirm it is green; a green push is not a substitute for the gate.
 - **Push the branch and open a PR.** Do **not** push to or merge straight into `main` —
   changes land via a reviewed, approved PR (squash-merge). Each PR carries its CHANGELOG
-  entry (and an ADR for non-trivial changes — see below).
+  entry (and an OpenSpec change for non-trivial changes — see below).
 - **After merge**, clean up: `git worktree remove .worktrees/<slug>` and delete the branch.
 
-## Documenting changes — CHANGELOG + ADR
+## Documenting changes — CHANGELOG + OpenSpec
 
-Every PR leaves a trace, so that «what and why we changed» does not get lost in the
+Every PR leaves a trace, so that what and why we changed does not get lost in the
 git/GitHub history. This is a repository rule, not an option:
 
 - **`CHANGELOG.md`** (root) — **one entry per PR**, reverse-chronologically.
-  Format: `## YYYY-MM-DD — <short title> (#<PR>)` + 1–2 lines of essence + a link to
-  an ADR, if there is one. **No version sections** — the service has no releases/tags, the deploy is
-  continuous. The entry is added in the same PR as the change.
-- **ADR** — for **non-trivial** changes (there is a design decision, a choice between
-  options, a non-obvious trade-off): `docs/decisions/NNNN-<slug>.md`, a continuous
-  4-digit numbering, by the template `docs/decisions/0000-template.md` (sections **Context /
-  Considered Options / Decision / Consequences**) — the problem, the considered options,
-  the rationale for the choice. The CHANGELOG entry links to the ADR.
+  Format: `## YYYY-MM-DD — <short title> (#<PR>)` + 1–2 lines of essence + a link to the
+  archived OpenSpec change, if there is one. **No version sections** — the service has no
+  releases/tags, the deploy is continuous. The entry is added in the same PR as the change.
+- **OpenSpec** (`openspec/`) — for **non-trivial** changes (there is a design decision, a choice
+  between options, a non-obvious trade-off). Plan it as an OpenSpec change rather than coding
+  blind: `openspec/changes/<slug>/` holds `proposal.md` (why + what), `design.md` (how + the
+  trade-off, in the spirit of the old ADRs: Context / Considered Options / Decision /
+  Consequences) and `tasks.md`, plus spec deltas. Drive it with the `/opsx:*` workflow
+  (`/opsx:propose` → `/opsx:apply` → `/opsx:archive`) or the `openspec` CLI. On completion the
+  change is **archived** under `openspec/changes/archive/<date>-<slug>/` and the affected specs
+  are updated. The CHANGELOG entry links the archived change.
+- **`openspec/specs/<capability>/spec.md`** is the **living behavior contract** (requirement +
+  WHEN/THEN scenarios) — the source of truth for what the system does. Keep it in sync when
+  behavior changes (the design rationale lives in the change's `design.md`; the behavior lives in
+  the spec). Validate with `openspec validate --specs --strict`.
 - **Trivial** changes (a typo, a dependency bump, a small thing without forks) — only
-  a line in CHANGELOG, without an ADR.
-- An ADR is **immutable after merge**. A decision that cancels a previous one is a new ADR with a
-  `Supersedes 000X` link; the old one's status changes to `Superseded by 000Y`.
+  a line in CHANGELOG, no OpenSpec change.
+
+> OpenSpec **replaces the former ADR process**: this migration is recorded as the archived change
+> `openspec/changes/archive/2026-06-28-adopt-openspec/`, and the old `docs/decisions/` ADR catalog
+> was removed (the records remain in git history). **Do not add new ADRs** — new design decisions
+> go through OpenSpec changes.
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5b5a8b5..4181471 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,10 +1,21 @@
 # Changelog
 
-subgen changes — one entry per PR, reverse-chronological. Non-trivial changes
-link to an ADR in [`docs/decisions/`](docs/decisions/). The rule and format are
-in [`AGENTS.md`](AGENTS.md) (section "Documenting changes"). There are no versions/tags:
+subgen changes — one entry per PR, reverse-chronological. Non-trivial changes link to an
+archived OpenSpec change in [`openspec/changes/archive/`](openspec/changes/archive/) (the former
+ADR catalog was removed; older entries below still mention their ADR by number). The rule and
+format are in [`AGENTS.md`](AGENTS.md) (section "Documenting changes"). There are no versions/tags:
 the service is not released, deploy is continuous.
 
+## 2026-06-28 — Migrate to OpenSpec (#121)
+
+Adopted [OpenSpec](https://github.com/Fission-AI/OpenSpec) (the `spec-driven` schema) as the
+planning and change-documentation process, replacing the ADR catalog (the `CHANGELOG` stays).
+Seeded a full spec baseline under `openspec/specs/` (12 capabilities, validated by
+`openspec validate --specs --strict`), added the `/opsx:*` workflow under `.claude/` (narrowed the
+`.claude` gitignore so it is tracked), rewrote the process in `AGENTS.md` / `CONTRIBUTING.md` /
+`README.md`, and **removed the `docs/decisions/` ADR catalog** (kept in git history). The
+migration's own rationale lives in `openspec/changes/archive/2026-06-28-adopt-openspec/`.
+
 ## 2026-06-28 — Feature worktree workflow (#120)
 
 Documented the per-feature workflow in `AGENTS.md`: every feature/fix is developed in its
@@ -37,7 +48,7 @@ Prepared the repository for a public release. Rewrote `README.md` for newcomers
 human-facing to English — `AGENTS.md`, `CHANGELOG.md`, all ADRs, `apitest/README.md`,
 `docs/subgen.md`, the admin UI (`internal/handlers/web/static/`), and all user-facing
 handler/error messages (unit tests and `apitest` assertions updated in lockstep). See
-[ADR-0009](docs/decisions/0009-public-ready-and-english-docs.md).
+ADR-0009.
 
 ## 2026-06-17 — Subscription: a popup of links from the backend (raw URL + clashmi deeplink) (#116)
 
@@ -49,7 +60,7 @@ catalog and the frontend hardcodes nothing (adding an engine/app = one catalog l
 shows only the title and a "Copy" button (the value is private). The `sub` shape in
 `GET /admin/api/users` changed from `{id,url}` to `{links:[{title,value}]}`; the clashmi
 deeplink's `name` = the profile title of the user's effective (custom, else base) config. See
-[ADR-0008](docs/decisions/0008-subscription-link-catalog.md).
+ADR-0008.
 
 Also in this PR: the "Subscription settings" block was moved to the top of the "Mihomo config"
 tab; leftover githooks were removed (the `make hooks` target and the local `core.hooksPath` — the
@@ -76,7 +87,7 @@ matchers were added for parity with the wiki (`SRC-IP-ASN`, `SRC-IP-SUFFIX`, `PR
 section in the base YAML). Sub-rules carry no `no-resolve` (mihomo does not parse it for them). UI —
 a recursive tree constructor; SUB-RULE is not implemented. Schema — migration
 `migrations/0004-mihomo-rule-children.notx.sql`. See
-[ADR-0006](docs/decisions/0006-recursive-routing-rules.md).
+ADR-0006.
 
 ## 2026-06-11 — Strict mihomo references: RULE-SET → rule-provider by id (#17)
 
@@ -85,7 +96,7 @@ rule-provider by surrogate id (`provider_id` FK); the save input and domain/read
 separate types (a draft with indices vs a domain with real ids), which removes the double meaning of
 `PolicyRef.GroupID`. Optional fields (`value`/`interval`/`tolerance`/`lazy`/`noResolve`) are
 pointers. The schema is migrated by the runner (`migrations/0003-strict-mihomo-refs.notx.sql` —
-rebuild with FK off outside a transaction). See [ADR-0005](docs/decisions/0005-strict-mihomo-refs.md).
+rebuild with FK off outside a transaction). See ADR-0005.
 
 ## 2026-06-11 — User: optional description for the admin panel (#15)
 
@@ -94,7 +105,7 @@ visible only in the admin UI): set on create/edit, shown as an icon with a
 tooltip in the table. The `users.description` column (nullable) is added by migration
 `migrations/0002-users-description.sql` via the runner. Service inputs were moved into the structs
 `entity.UserCreateParams` / `entity.UserEditParams` (removed `entity.ConnectionSelection`).
-See [ADR-0004](docs/decisions/0004-optional-user-description.md).
+See ADR-0004.
 
 ## 2026-06-11 — Request validation — in the service layer, not in OpenAPI (#19)
 
@@ -109,7 +120,7 @@ provider-check URL is not a special case (nor is a malformed URL → `RulesetChe
 public and are imported in apitest (no duplication). In tests `gomock.Any()` was kept
 only for the context — the other arguments are checked exactly (matchers for random uuid/subId).
 `required`/`type`/`format` were kept (the contract shape). See
-[ADR-0003](docs/decisions/0003-validation-in-code.md).
+ADR-0003.
 
 ## 2026-06-11 — Ordered migration runner (#18)
 
@@ -117,10 +128,10 @@ Manual `*.manual.sql` was replaced by the runner `migrations.Apply` (`repository
 instead of `ExecContext(Schema)`): `0001-init.sql` — the immutable baseline, then `NNNN-*.sql`
 by name, the application fact — in `schema_migrations`, each migration in a transaction,
 fail-fast + log. Connection PRAGMA (incl. `journal_mode=WAL`) moved into the DSN. The section on
-migrations in `AGENTS.md` was rewritten. See [ADR-0002](docs/decisions/0002-ordered-migration-runner.md).
+migrations in `AGENTS.md` was rewritten. See ADR-0002.
 
 ## 2026-06-11 — Documenting convention: CHANGELOG + ADR (#16)
 
 Introduced `CHANGELOG.md` (this file) and the ADR catalog `docs/decisions/`; the rule is recorded in
 `AGENTS.md`. The format "one entry per PR, no versions" was chosen.
-See [ADR-0001](docs/decisions/0001-adopt-changelog-and-adr.md).
+See ADR-0001.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index bba08ec..3665784 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -75,20 +75,26 @@ Highlights:
   (`fmt.Errorf("dep.Method: %w", err)`); user-facing text lives as constants in the handler
   package, mapped from sentinels (domain → 4xx, infra → 5xx).
 - **User-facing text is English.** Don't introduce non-English strings in code or docs (the
-  admin UI's product labels are English too). See
-  [ADR-0009](docs/decisions/0009-public-ready-and-english-docs.md).
+  admin UI's product labels are English too).
 - **Validation lives in the service layer** (sentinel errors), not in the OpenAPI schema.
 
-## Documenting changes — CHANGELOG + ADR
+## Documenting changes — CHANGELOG + OpenSpec
 
 Every PR leaves a trail:
 
 - **`CHANGELOG.md`** — one entry per PR, reverse-chronological:
-  `## YYYY-MM-DD — <short title> (#PR)` + 1–2 lines, plus an ADR link if there is one.
-- **ADRs** — for non-trivial changes (a design decision / trade-off), add
-  `docs/decisions/NNNN-<slug>.md` from `docs/decisions/0000-template.md` (Context /
-  Considered Options / Decision / Consequences). ADRs are immutable once merged; a later
-  decision that reverses one is a new ADR that `Supersedes` it.
+  `## YYYY-MM-DD — <short title> (#PR)` + 1–2 lines, plus a link to the archived OpenSpec
+  change if there is one.
+- **OpenSpec** (`openspec/`) — for non-trivial changes (a design decision / trade-off), plan
+  it as an OpenSpec change: `openspec/changes/<slug>/` with `proposal.md` / `design.md` /
+  `tasks.md` and spec deltas, then archive it under `openspec/changes/archive/` and update the
+  affected `openspec/specs/`. Drive it with the `/opsx:*` slash commands (committed under
+  `.claude/`) or the CLI (`npx @fission-ai/openspec`). Validate specs with
+  `openspec validate --specs --strict`.
+- The living behavior contract is `openspec/specs/<capability>/spec.md`; keep it in sync when
+  behavior changes. OpenSpec replaces the former ADR process (the old `docs/decisions/` catalog
+  was removed; do not add new ADRs). This migration's own record is the archived change
+  `openspec/changes/archive/2026-06-28-adopt-openspec/`.
 
 ## Security & secrets
 
@@ -100,4 +106,4 @@ per-client configs must never land in git.
 
 - Branch off `main`, keep the change focused, and make sure `make all` (or at least lint +
   unit + integration) is green.
-- Include the `CHANGELOG.md` entry (and an ADR if warranted) in the same PR.
+- Include the `CHANGELOG.md` entry (and an OpenSpec change if warranted) in the same PR.
diff --git a/README.md b/README.md
index 11115c4..0c8bcb1 100644
--- a/README.md
+++ b/README.md
@@ -222,7 +222,8 @@ assets. There is no `App` oracle — dependencies flow bottom-up
 
 - [`docs/subgen.md`](docs/subgen.md) — design rationale, operations, admin-panel tour, deploy.
 - [`AGENTS.md`](AGENTS.md) — code style & conventions (layers, contracts, testing, errors).
-- [`docs/decisions/`](docs/decisions) — Architecture Decision Records (ADRs).
+- [`openspec/`](openspec) — the living spec baseline (`specs/`) and the OpenSpec change workflow
+  (it replaces the former ADR catalog).
 - [`CHANGELOG.md`](CHANGELOG.md) — one entry per PR.
 - [`openapi/`](openapi) — the HTTP contract (source of the generated server).
 - [`apitest/README.md`](apitest/README.md) — black-box API tests against real 3x-ui.
diff --git a/apitest/auth/login_test.go b/apitest/auth/login_test.go
index cf7ab88..7907a69 100644
--- a/apitest/auth/login_test.go
+++ b/apitest/auth/login_test.go
@@ -53,7 +53,7 @@ func (s *AuthSuite) TestLoginPost() {
 
 	s.Run("empty_fields", func() {
 		// Schema no longer carries minLength; empty creds reach the handler and just fail
-		// the constant-time compare like any wrong creds → 401 (ADR-0003: validation in code).
+		// the constant-time compare like any wrong creds → 401 (value validation lives in the service).
 		res, err := s.fresh().Login("", "")
 		s.Require().NoError(err)
 		s.Equal(http.StatusUnauthorized, res.Status, "empty creds are wrong creds → 401")
diff --git a/apitest/users/create_test.go b/apitest/users/create_test.go
index d7cf8f5..084ad35 100644
--- a/apitest/users/create_test.go
+++ b/apitest/users/create_test.go
@@ -72,7 +72,7 @@ func (s *UserSuite) TestCreateValidation() {
 
 	s.Run("empty_name", func() {
 		// Schema no longer carries minLength; the empty name reaches validateName → friendly
-		// charset message (ADR-0003: validation in code).
+		// charset message (value validation lives in the service).
 		res, err := s.API().CreateUser("", []int64{smartN1})
 		s.Require().NoError(err)
 		s.Equal(http.StatusBadRequest, res.Status)
diff --git a/apitest/users/edit_test.go b/apitest/users/edit_test.go
index 85bc5d1..fdfafcb 100644
--- a/apitest/users/edit_test.go
+++ b/apitest/users/edit_test.go
@@ -109,7 +109,8 @@ func (s *UserSuite) TestEditValidation() {
 
 	s.Run("no_connection", func() {
 		// An absent inbound list (nil → null) is rejected as a generic 400 by the kept
-		// `required` (ADR-0003 removed minItems but not required); the binding is unchanged.
+		// `required` (value constraints like minItems live in the service, not the schema, but
+		// `required` stays); the binding is unchanged.
 		res, err := s.API().EditUser(u.ID, nil)
 		s.Require().NoError(err)
 		s.Equal(http.StatusBadRequest, res.Status)
diff --git a/docs/decisions/0000-template.md b/docs/decisions/0000-template.md
deleted file mode 100644
index 97881a6..0000000
--- a/docs/decisions/0000-template.md
+++ /dev/null
@@ -1,24 +0,0 @@
-# NNNN — <Decision title>
-
-- **Status:** Proposed | Accepted | Superseded by 000Y
-- **Date:** YYYY-MM-DD
-- **PR:** #<number>
-
-## Context
-
-The problem/need, what triggered it, what constraints. Why we are changing anything at all.
-
-## Considered Options
-
-- **Option A** — the gist; pros/cons.
-- **Option B** — the gist; pros/cons.
-- (more, as needed)
-
-## Decision
-
-What we chose and **why exactly this** — which trade-off tipped the scale.
-
-## Consequences
-
-What follows from the choice: what becomes easier/harder, what is now impossible, what else it affects,
-what further steps/constraints (both positive and negative).
diff --git a/docs/decisions/0001-adopt-changelog-and-adr.md b/docs/decisions/0001-adopt-changelog-and-adr.md
deleted file mode 100644
index bb7cd79..0000000
--- a/docs/decisions/0001-adopt-changelog-and-adr.md
+++ /dev/null
@@ -1,43 +0,0 @@
-# 0001 — Documentation convention: CHANGELOG + ADR
-
-- **Status:** Accepted
-- **Date:** 2026-06-11
-- **PR:** #16
-
-## Context
-
-«Why we decided this way» was getting lost in subgen: the context of a change lived only in the PR
-discussion and in the author's head, while only diffs and one-line commit messages remained in the
-repository. A couple of months later it is already hard to reconstruct the motivation of an
-architectural choice. We need a lightweight but mandatory mechanism that records both *what*
-changed and *why*.
-
-## Considered Options
-
-- **CHANGELOG only (Keep a Changelog)** — the keepachangelog.com standard: `[Unreleased]` +
-  `Added/Changed/Fixed/Removed` sections, tied to versions. Recognizable, but
-  designed for versioned releases, which subgen does not have (continuous deploy, without
-  tags), and it is not the place for an elaborate «why» with an analysis of options.
-- **ADR only** — detailed decisions in `docs/decisions/`, but without a consolidated list
-  of changes: there is no quick «what even happened recently».
-- **CHANGELOG (per-PR, without versions) + ADR for the non-trivial** *(chosen)* — a short
-  entry per PR as an index of changes plus a separate ADR with the problem/options/
-  rationale wherever there is a design decision. The CHANGELOG links to the ADR.
-- **Leave it as is** — rely on the PR history. This is exactly the loss of context we are fixing.
-
-## Decision
-
-We introduce **both** artifacts: `CHANGELOG.md` (one entry per PR, reverse-chronologically,
-without version sections) and an ADR catalog `docs/decisions/NNNN-slug.md` (Context / Considered
-Options / Decision / Consequences) for non-trivial changes. The rule is in `AGENTS.md`.
-The «per-PR without versions» format was chosen because the deploy is continuous and there is nothing
-to tie the version sections of Keep a Changelog to.
-
-## Consequences
-
-- Every PR is obliged to add a CHANGELOG entry; a non-trivial one — also an ADR. A small
-  constant overhead, paid back by the preserved context.
-- A stable referenceable unit of a decision appears (`ADR-NNNN`), referenced by the
-  CHANGELOG, code reviews and subsequent ADRs.
-- ADRs are immutable: a revision is a new ADR with `Supersedes`, not an edit of the old one.
-- This PR is the first one under the convention and follows it itself (a CHANGELOG entry + this ADR).
diff --git a/docs/decisions/0002-ordered-migration-runner.md b/docs/decisions/0002-ordered-migration-runner.md
deleted file mode 100644
index 97859e0..0000000
--- a/docs/decisions/0002-ordered-migration-runner.md
+++ /dev/null
@@ -1,66 +0,0 @@
-# 0002 — An ordered migration runner instead of manual ones
-
-- **Status:** Accepted
-- **Date:** 2026-06-11
-- **PR:** #18
-
-## Context
-
-The DB schema was applied with a single embedded `init.sql` (`migrations.Schema`,
-`CREATE … IF NOT EXISTS`) on start, while structural changes to existing tables
-(`ALTER TABLE …`) were done **by hand**: a one-off `*.manual.sql` file that no code
-runs — the operator must remember to execute it on prod. This is fragile: easy to
-forget, there is no trace of «what is already applied», ordering and atomicity are on the human's
-conscience. We need a mechanism that itself, and in the right order, brings any base (fresh or
-existing) up to the current schema, failing loudly on error.
-
-## Considered Options
-
-- **Keep manual migrations** (`init.sql` + `*.manual.sql`) — minimal code, but exactly the
-  fragility we are fixing: a manual step, no record of what was applied, easy to get schema drift.
-- **`CREATE/ALTER … IF NOT EXISTS`, run everything every start** — without a tracking table. But
-  SQLite cannot do `ADD COLUMN IF NOT EXISTS`, so an `ALTER` on a repeat start would fail;
-  one would have to «probe» `PRAGMA table_info` — a homemade half-migrator.
-- **An external migration library** (goose / golang-migrate) — functional, but pulls in a
-  dependency and its own model of files/CLI for the sake of a few files; for an embedded schema in
-  a single binary it is overkill.
-- **Our own runner of ordered files + a tracking table** *(chosen)* — `0001-init.sql` as the
-  baseline, then `NNNN-*.sql`; applied by name order, each in a transaction, the fact
-  of application written to `schema_migrations`. Idempotent, without dependencies.
-
-## Decision
-
-We introduce a runner `migrations.Apply(ctx, db)` (the package `migrations`, files `embed.go` +
-`run.go`), which `repository.Open` calls instead of `ExecContext(Schema)`:
-
-- `0001-init.sql` — the **baseline** (the full schema-as-of-now); then `0002-*.sql`, …. All files are
-  `NNNN-`-prefixed, so the ordinary lexicographic name sort = the apply order
-  (without special logic and without pinning the baseline).
-- The table `schema_migrations(name PRIMARY KEY, applied_at)` stores what was applied; each
-  file is applied **once**, a repeat start is a no-op.
-- Each migration — in **its own transaction** together with the write to `schema_migrations`
-  (atomically: a crash mid-file leaves no «half-applied» state and does not write the fact).
-- On error `Apply` returns it → `main` crashes (`log.Fatal`); each apply is
-  logged (`slog.Info`).
-- **The connection PRAGMA have moved to the DSN** (`open.go`: `busy_timeout`, `foreign_keys`,
-  `journal_mode=WAL`), not into `0001-init.sql` — `PRAGMA journal_mode=WAL` cannot be executed
-  inside the transaction the runner wraps the file in, therefore migrations are pure DDL.
-
-This **cancels** the prior «DB migrations — by hand only» (the section in `AGENTS.md` was rewritten).
-Our own, not a library — because the volume (an embedded schema of a single binary) does not justify a
-dependency, and the semantics are trivial.
-
-## Consequences
-
-- Any base is brought up to the current schema automatically and in order; `*.manual.sql`
-  are no longer needed (the pattern was removed from the rules). A structural change = a new
-  `NNNN-*.sql`, and that is all.
-- An existing prod base is adopted safely: `schema_migrations` is created empty, the
-  baseline (`CREATE … IF NOT EXISTS`) is a no-op on a repeat run and is marked as applied, then
-  `NNNN-*.sql` land on top. A separate «tracking backfill» is not needed.
-- `0001-init.sql` is now an **immutable baseline**: schema edits go only via new
-  files, not by editing the baseline (otherwise it diverges from already-adopted bases).
-- PRAGMA — in one place, in the DSN; migrations are obliged to be pure DDL (PRAGMA that change the
-  journal mode must not be put into a migration file).
-- Rolling back migrations is not implemented (forward-only) — deliberately: for a continuous deploy
-  «forward + a new fix file» is simpler and safer than down scripts.
diff --git a/docs/decisions/0003-validation-in-code.md b/docs/decisions/0003-validation-in-code.md
deleted file mode 100644
index b4a5b1f..0000000
--- a/docs/decisions/0003-validation-in-code.md
+++ /dev/null
@@ -1,68 +0,0 @@
-# 0003 — Request validation in code, not in the OpenAPI schema
-
-- **Status:** Accepted
-- **Date:** 2026-06-11
-- **PR:** #19
-
-## Context
-
-ogen generates server validators from schema constraints (`minLength`, `minItems`,
-`minimum`, …) and calls them on request decode. On a violation the response is a generic
-`400 {"errMessage":"Bad request"}` (the central `ErrorHandler`), **without a binding
-to the field**: a user editing a specific field does not understand what is wrong.
-
-Disabling the **generation** of these validators while keeping the constraints themselves in the
-`.yaml` as a contract declaration is something ogen cannot do: there is no
-`server/request/validation` feature, and `x-ogen-validate` only adds custom validators. So the choice is
-binary: either the constraint is in the schema (ogen validates, generic message), or it is not there
-(we validate in code, a precise message). An understandable localized message was deemed more
-important than declarativeness.
-
-## Considered Options
-
-- **Validation by schema (as it was)** — declarative, free (codegen), cuts off at the edge;
-  but the message is generic («Bad request»), bad UX, and some rules cannot be expressed by the schema.
-- **Duplicate (schema + code)** — both the contract and a precise message; but with the constraint in the
-  schema ogen cuts the request **before** the handler, and the code check on the HTTP path is
-  dead → a formal duplicate.
-- **Custom ogen templates** — override the request decode so as not to call `.Validate()`;
-  global, fragile (a resync on every ogen upgrade), high maintenance.
-- **All value validation — in code** *(chosen)* — remove value constraints from the schema,
-  check in the handler/service with a sentinel + a localized message.
-
-## Decision
-
-- **All value constraints** (`minLength`, `minItems`,
-  `minimum`) were removed from `openapi/*.yaml`. **Kept** are `required`, `type`, `format` — they define the shape of the contract
-  and the generated Go types (this is not «value validation», and ogen validates
-  presence/type by them, which is what we need).
-- **Validation — in the service layer**, with sentinel errors in `entity`; the handlers are thin and map a
-  sentinel into a typed 4xx with a local message constant. Where there was no service — it was
-  introduced: **`internal/service/nodes`** owns node validation (the
-  `entity.ErrValidation*` family — name/host/URL/base-path/inbounds) plus save/delete. **Inbound
-  referential integrity we do NOT pre-check**: deleting a node/removing an inbound that still has a
-  reference (a user connection or a mihomo rule/group) is rejected by the DB FK (RESTRICT), and the
-  repository translates the violation into `entity.ErrInboundReferenced` — the handler maps it to
-  400. Some validations were already in the service/domain and were kept: `validateName`,
-  `ErrNoConnectionSelected`, `PolicyRef.Valid()`.
-- **Surrogate ids (PK) we do NOT validate.** Checking `id ≥ 1` is meaningless: a non-existent id
-  (whether `-100` or a valid-but-absent `1233`) yields not-found on read either way —
-  a separate «id format validation» carries no meaning. Removed.
-- Where the old behavior already correctly rejected the input without an openapi guard — it was kept: empty
-  creds → 401 (constant-time compare), empty path segments do not match the route, an empty/unknown
-  `PolicyRef.kind` → `validateRef`. An empty provider-check URL we do **not** validate separately: it is
-  no different from a malformed URL — both are unreachable and yield `RulesetCheckUnreachable`
-  (there is no emptiness guard in the handler).
-
-## Consequences
-
-- Validation errors are precise, localized, bound to the field; in the service, covered by
-  unit tests. The handlers stay thin (a service call + sentinel mapping).
-- `openapi/*.yaml` stops being a source of enforced value constraints (only the shape of the
-  contract). **A convention for the future**: values are validated in the service with sentinel errors,
-  into the schema we put only `required`/`type`/`format`; surrogate ids we do not validate.
-- Node validation moved from `web` (the handler layer) into `internal/service/nodes`; `web` no longer
-  holds the message mapping — the human error text lives in local constants in each
-  handler (`node_save`/`node_delete` etc.), exported for apitest.
-- A small downside: the limits no longer self-document in the schema for third-party tooling.
-- The risk of a «duplicate» and the generic vague 400 on a schema error are removed.
diff --git a/docs/decisions/0004-optional-user-description.md b/docs/decisions/0004-optional-user-description.md
deleted file mode 100644
index 571bd26..0000000
--- a/docs/decisions/0004-optional-user-description.md
+++ /dev/null
@@ -1,58 +0,0 @@
-# 0004 — Optional user description: nillable + input structs
-
-- **Status:** Accepted
-- **Date:** 2026-06-11
-- **PR:** #15
-
-## Context
-
-The admin needs the ability to attach an arbitrary text note to a user
-(«work laptop», «issued on such-and-such date»), visible only in the admin UI and not affecting
-anything in the 3x-ui provisioning. The field is optional — most users do not have it. The question: how
-to represent «no description» in the domain and in the DB, and how to thread one more optional
-parameter through `CreateUser`/`EditUser` without turning them into walls of positional arguments.
-
-## Considered Options
-
-- **`NOT NULL DEFAULT ''` + `Description string`** — the simplest: an empty string = «no
-  description». But «optional» is then not reflected in the type — `""` and «not set» are indistinguishable, easy
-  to forget the normalization, the domain lies about optionality. (This was the first version of the PR;
-  rejected at review.)
-- **A nullable column + `Description *string`** *(chosen for the representation)* — `NULL`/`nil`
-  = «not set», a non-empty string = a value. «optional ⇒ nillable» honestly in the type; one
-  canonical representation of emptiness (NULL).
-- **An extra positional argument** `CreateUser(ctx, name, description, sel)` —
-  two adjacent `string`s next to each other (name/description) are easy to swap, the signature
-  grows. Rejected at review.
-- **An input struct** `UserCreateParams`/`UserEditParams` *(chosen)* — named fields,
-  extensible without breaking the signature.
-
-## Decision
-
-- **`Description *string`** through the layers (entity → repo → service → handlers): `nil` =
-  not set. The column `users.description` is **nullable**; the repository **scans it straight
-  into a `*string`** (the standard `database/sql` + modernc put `NULL`→`nil`, a value→a string
-  themselves — a `sql.Null*` proxy is not needed). The service normalizes empty/whitespace to `nil` (one
-  representation = NULL). The read API (`GET /admin/api/users`) returns `description` **only
-  when set** (the field is optional in the schema), the write (`create`/`edit`) accepts
-  an optional string.
-- **Service inputs — structs** `entity.UserCreateParams{Name, Description, InboundIDs}`
-  and `entity.UserEditParams{ID, Description, InboundIDs}` instead of positional arguments.
-  The former wrapper `entity.ConnectionSelection` (a relic of the old architecture) was removed — the
-  set of inbounds travels as a bare `[]int64`.
-- **The length is validated by the service** (`validateDescription` → `entity.ErrDescriptionTooLong`,
-  ≤500 runes), the handler maps it to 400 — not by an «invisible» `maxLength` in the OpenAPI schema. This is
-  consistent with how `name` is validated (`validateName` in the service).
-- The column is added by the migration **`migrations/0002-users-description.sql`** via the runner
-  ([ADR-0002](0002-ordered-migration-runner.md)) — not by editing the `0001-init.sql` baseline.
-
-## Consequences
-
-- «No description» has a single representation (NULL/`nil`) — there is no ambiguity of
-  `""` vs not set; less chance of forgetting the normalization.
-- `CreateUser`/`EditUser` are extensible with new fields without changing the signature (via the struct).
-- Length validation — in one place (the service), visible and covered by a unit test; OpenAPI does not
-  duplicate it.
-- The UI shows the description as an icon with a tooltip next to the nickname; in the create/edit form — a textarea.
-- This is the first feature migration on top of the runner (`0002-*.sql`) — it confirms that the schema grows
-  by new files, not by editing the baseline.
diff --git a/docs/decisions/0005-strict-mihomo-refs.md b/docs/decisions/0005-strict-mihomo-refs.md
deleted file mode 100644
index b45426b..0000000
--- a/docs/decisions/0005-strict-mihomo-refs.md
+++ /dev/null
@@ -1,86 +0,0 @@
-# 0005 — Strict typed references in the mihomo config (RULE-SET → provider by id)
-
-- **Status:** Accepted
-- **Date:** 2026-06-11
-- **PR:** #17
-
-## Context
-
-`RoutingRule` addressed a rule-provider dirtily: for `RULE-SET` the provider name lay as a
-string in `RoutingRule.Value` (validation — a match by name, render — the name went into the YAML
-as is). This violated the project rule «a reference to an entity = by id; a string — only
-if it is itself a string payload» (AGENTS.md, «entity — self-documenting types»):
-a provider is an entity, and `Value` must be a pure string payload (domain/ip/
-port), empty for `RULE-SET` and `MATCH`.
-
-Groups and inbounds were already addressed by id (`PolicyRef.GroupID`/`InboundID`), but a group
-had a hidden wart: the domain field `PolicyRef.GroupID` carried a DIFFERENT meaning by direction —
-on input into `SaveMihomoConfig` it is an index into the array (ids are not assigned yet),
-on read from the DB it is a real id. One field — two meanings.
-
-mihomo has no numeric ids: in the output YAML proxy-groups and rule-providers are addressed by
-NAME (rule-providers are a map, the key = the name). That is, the name is the PK of the output
-document. Inside subgen, which edits this document, the name is a mutable form field.
-
-## Considered Options
-
-- **Keep the name as the reference, but type it** (`ProviderRef{Name}` instead of a string in
-  `Value`) — honest to the fact that the name is the PK of the mihomo document; but the join key inside the
-  editor becomes a mutable string: renaming a provider breaks the reference (this was the current
-  behavior + the warning «non-existent provider»).
-- **A round-trip for an id on every «+»** (the new-provider endpoint returns an id) — gives real
-  ids at the editing stage, but breaks atomicity (save is currently a wholesale replace in
-  one transaction), leaves half-assembled configs in the DB (orphan GC is needed), and the ids are
-  ephemeral anyway (the next full save recreates them). Chattiness without a durable benefit.
-- **A surrogate id + a reference by index on the wire** *(chosen)* — the provider gets a
-  surrogate `id`, `RULE-SET` references it; the name is resolved into the YAML key only on
-  render (as already done for groups). At the boundary with the frontend the reference travels as an array
-  index (a correlation id), resolved into an id inside `SaveMihomoConfig`. Rename-safe, gives
-  FK integrity, symmetric to groups.
-- **Switch to incremental-diff persistence** (durable ids, in-place UPDATE) — would remove the
-  id ephemerality and the index/id wart itself; but it complicates save (the diff, deletions, FK order) and
-  at the config sizes (a handful of groups/providers) does not pay off.
-
-## Decision
-
-We take a surrogate id + a reference by index, and at the same time **split the types of the save input and
-domain/read** in order to remove the field's double meaning:
-
-- **`RuleProvider`** += `ID int64`; **`RoutingRule`** += `ProviderID *int64` (nil except for
-  `RULE-SET`), `Value` — a pure payload.
-- The domain types (`RoutingRule`/`ProxyGroup`/`RuleProvider`/`PolicyRef`) carry only
-  real ids — they are consumed by reads from the DB and the render.
-- A new **draft** type family (`ConfigDraft`/`RuleDraft`/`GroupDraft`/`RefDraft`)
-  carries indices — it is produced by `DecodeConfig` and consumed by `SaveMihomoConfig`. Index→
-  id is resolved inside save (in local slices), not in the type.
-- DB: `mihomo_rule_providers` gets `id INTEGER PRIMARY KEY AUTOINCREMENT` +
-  `UNIQUE(config_id,name)`; `mihomo_routing_rules` += `provider_id`; the optional columns
-  (`value`/`interval`/`tolerance`/`lazy`) become nullable. The schema travels via the migration
-  runner — `migrations/0003-strict-mihomo-refs.notx.sql`: a rebuild of the three tables +
-  a backfill of `provider_id` from names + a cleanup of `value`. Since the rebuild requires
-  `PRAGMA foreign_keys=OFF` (a no-op inside a transaction), the runner was extended with a **`.notx` mode**
-  (the migration runs outside a transaction, writes itself into `schema_migrations`) — a departure
-  from ADR-0002 «each in a transaction», deliberate and documented.
-- The wire does not split (it is already index-based both ways) — only `providerIdx` was added to
-  `MihomoRule`. The provider name is not used on the wire as a reference.
-
-Why an index/correlation id, and not the name: with a wholesale replace providers/rules are
-recreated by every save, there is no durable id in principle, so a reference at the editing
-stage must be either by name (mutable) or by position (a correlation
-id). Position is rename-safe and symmetric to groups.
-
-## Consequences
-
-- Renaming a provider no longer breaks RULE-SET references (as with groups).
-- FK integrity `rule → provider` within a snapshot appears; a duplicate name is caught
-  as `UNIQUE` (2067), translated into `entity.ErrRuleProviderNameTaken` (the detector matches both
-  PK 1555 and UNIQUE 2067 — the behavior is preserved).
-- Draft and domain never coexist in one graph (save: wire→ConfigDraft→DB; read:
-  DB→domain), so no field carries «an index on input / an id on output». The cost — a
-  parallel family of draft types (introduced only where there is a reference by index; the
-  provider carries no references → it reuses the domain `RuleProvider` with an empty ID).
-- The prod migration is manual and one-off, requires a backup and a read-only check (whether there are
-  RULE-SET rules, whether the names match); the order and the checks are described in the migration file itself.
-- The cleanliness of the separation rests on the wholesale replace; switching to incremental-diff
-  would require a hybrid ref type (either an index or an id) — deliberately deferred.
-- AND/OR/NOT (logical rules) will land on this cleaned-up model as separate work.
diff --git a/docs/decisions/0006-recursive-routing-rules.md b/docs/decisions/0006-recursive-routing-rules.md
deleted file mode 100644
index a3daefb..0000000
--- a/docs/decisions/0006-recursive-routing-rules.md
+++ /dev/null
@@ -1,111 +0,0 @@
-# 0006 — Logical routing rules (AND/OR/NOT) as a recursive rule
-
-- **Status:** Accepted
-- **Date:** 2026-06-16
-- **PR:** #114
-
-## Context
-
-The routing-rule model was a flat single matcher:
-`RoutingRule{Type, Value, ProviderID, NoResolve, Target}` — one type, one value, one
-target. It does not express mihomo's logical/composite rules (`AND`/`OR`/`NOT`), whose
-payload is a nested list of sub-rules: `LOGIC,((TYPE,VAL),(TYPE,VAL)),TARGET`. This
-blocked a real operational need — silencing QUIC
-
-```
-AND,((NETWORK,UDP),(DST-PORT,443)),REJECT-DROP
-```
-
-(it forces HTTP/3 to fall back to TCP; fixes App Store / YouTube hangs under TUN+fake-ip)
-— it could not be assembled from the UI.
-
-Targets are already typed via `PolicyRef` (see [ADR-0005](0005-strict-mihomo-refs.md)) —
-the gap was exclusively on the matchers' side. Additionally: the operator could write a
-`sub-rules` section into the base YAML and hit a collision with generation (the key was not in `GeneratedKeys`).
-
-Cross-checking the `ruleTypes` registry against the mihomo wiki revealed four more missing simple
-matchers: `SRC-IP-ASN`, `SRC-IP-SUFFIX`, `PROCESS-PATH-WILDCARD`, `PROCESS-NAME-WILDCARD`.
-
-Constraints discovered from the mihomo source (`rules/logic`): `NOT` takes exactly one
-sub-rule; sub-rules are parsed via `ParseRulePayload(payload, parseParams=false)` —
-**parameters (incl. `no-resolve`) inside a logical sub-rule are not extracted**, that is,
-a sub-rule does not carry `no-resolve`. `SUB-RULE` (a reference to a named sub-rule group) is
-a separate large feature (named sub-rule groups = a second editor); by the
-owner's decision in this iteration it is **not implemented**, only the base-YAML hole is closed.
-
-## Considered Options
-
-### The sub-rule type model
-
-- **A. A single recursive type.** `RoutingRule` (and the save-side `RuleDraft`) are recursive: a logical
-  rule carries sub-rules in `Children []RoutingRule` — of the same structure; `Target`
-  becomes optional (`*PolicyRef`) — the top level has it, a sub-rule does not.
-  Pros: one type, no «second entity»; exactly the model mihomo itself has (a rule
-  and a sub-rule are one). Cons: a sub-rule carries inapplicable fields (`Target`/`NoResolve`),
-  which validation forbids (a positional invariant top-level vs child).
-- **B. A separate sub-condition type** (`RuleCondition`/`ConditionDraft`) — only the needed fields
-  (`Type/Value/Provider/Children`), without a target. Pros: each type carries only its own. Cons:
-  two parallel recursive types + a separate table + duplication of decode/render/clone;
-  over-engineering for what is essentially one entity.
-
-### Storage
-
-- **A. A self-referential `mihomo_routing_rules`** (`parent_id` → self, `target_kind` nullable).
-  A sub-rule — a row of the same table with `parent_id` and without a target. A CHECK pins the invariant
-  `(parent_id IS NULL) = (target_kind IS NOT NULL)`. Pros: one table, save/read/clone
-  — one pass; `DELETE … WHERE config_id` removes the whole tree (every row has
-  `config_id`). Cons: a rebuild of the table is needed (target_kind → nullable) — a `.notx` migration.
-- **B. A separate table** `mihomo_rule_conditions`. Cons: a «second entity» in the DB, three
-  places of recursion (save/read/clone) + a separate provider FK; it contradicts the single type.
-- **C. A JSON blob** of sub-rules. Cons: references to a provider inside the blob are not FKs; it violates
-  the typed-references invariant (AGENTS). Rejected immediately.
-
-## Decision
-
-- **A single recursive type (A) + a self-referential table (A).** `RoutingRule.Children
-  []RoutingRule`, `Target *PolicyRef` (nil only on a sub-rule); the save mirror —
-  `RuleDraft.Children []RuleDraft`, `Target *RefDraft`. Separate `RuleCondition`/
-  `ConditionDraft` and a `mihomo_rule_conditions` table are **not introduced** — that was
-  over-engineering (a rule and a sub-rule are one entity, as in mihomo). Storage —
-  `mihomo_routing_rules` with `parent_id` (the migration `0004-*.notx.sql`, a rebuild with a nullable
-  `target_kind`). The JSON blob was rejected as violating typed references.
-- **The invariant — in code, positionally.** `RuleDraft.Valid()` — a position-independent
-  per-type check (a logical one carries no value/provider/no-resolve; `Children` only on a
-  logical one). A recursive `validateRule(r, top, …)` pins the positional part: a top-level one must
-  have a target (`ErrTargetRequired`), a sub-rule — must not (`ErrChildTarget`); `NOT`
-  exactly one, `AND`/`OR` ≥2; `MATCH` cannot be a sub-rule (`ErrMatchChild`); the provider index
-  in range; a sub-rule does not carry `no-resolve`.
-- **`no-resolve` on sub-rules — no.** Matches the mihomo parser and removes the field from the
-  sub-rule (only the top-level one carries it).
-- **The wire — `MihomoRule` is recursive.** `target` is optional (not `required`), `children[]` —
-  a self-`$ref`; there is no separate `MihomoCondition`. The top-level/child invariant — in the service, not
-  in the schema (per the AGENTS convention).
-- **`sub-rules` → `GeneratedKeys`.** Closes the base-YAML hole (save rejects, render
-  strips); subgen does not generate named sub-rule groups. SUB-RULE as a rule type was not
-  added.
-- **Matcher parity:** + `SRC-IP-ASN`, `SRC-IP-SUFFIX`, `PROCESS-PATH-WILDCARD`,
-  `PROCESS-NAME-WILDCARD` (simple, without special options).
-- **UI:** a recursive `rule-node` component (a tree with indents). Reordering
-  sub-rules is **intentionally not implemented** — AND/OR/NOT are commutative, order does not affect
-  matching (and it removes the conflict of nested SortableJS). Dragging top-level
-  rules is preserved (a row + its sub-rules are wrapped in a single draggable `.rule-item`).
-
-## Consequences
-
-- An arbitrary recursion `AND(AND(OR(...),NOT(...)),...)` round-trips DB ↔ render ↔
-  decode; the QUIC rule is assembled from the UI and rendered verbatim.
-- One table for rules and sub-rules: save — a recursive `insertRules` (a per-node
-  insert, `LastInsertId` → `parent_id`); read — assembling the tree in memory from a single query;
-  clone — one pass over `ORDER BY id` (parent before child) with a remap of
-  parent/provider/group. `DELETE … WHERE config_id` removes the whole tree.
-- A sub-rule carries inapplicable fields (`Target`/`NoResolve`), which the validator forbids;
-  this is a deliberate cost of the single type (fewer types matters more than «every field is applicable»).
-- Sub-rules do not reference inbounds (they are matchers, not targets) → the per-subscriber drop
-  works only by the rule's `Target`; the only render «failure» of a sub-rule is
-  an unresolved RULE-SET provider (a config error, log + drop of the rule).
-- Sub-rules do not carry `no-resolve` — if it is ever needed by mihomo's logic in the future, it
-  will require both support in the mihomo parser and an extension of the model.
-- The sub-rule order in the UI is not editable; if it is ever needed — it is added
-  trivially (the model is already ordered by `position`).
-- SUB-RULE (named sub-rule groups) remains a future task; `sub-rules`
-  is reserved for subgen, so it can be introduced later without a key migration.
diff --git a/docs/decisions/0008-subscription-link-catalog.md b/docs/decisions/0008-subscription-link-catalog.md
deleted file mode 100644
index 3df8ebd..0000000
--- a/docs/decisions/0008-subscription-link-catalog.md
+++ /dev/null
@@ -1,58 +0,0 @@
-# 0008 — Subscription-link catalog on the backend
-
-- **Status:** Accepted
-- **Date:** 2026-06-17
-- **PR:** #116
-
-## Context
-
-In the users list the "Subscription" column was a single "Mihomo" button that copied the one
-subscription URL (`sub.url` in the `GET /admin/api/users` response). We need to copy **several**
-things per user: the Mihomo subscription URL itself and the Clashmi app deeplink
-(`clashmi://install-config?url=<enc>&name=<title>&overwrite=false`), and in the future others
-(new engines, new client apps).
-
-Hard requirement: **the frontend must not hardcode which links exist or what their titles are** —
-otherwise every new client/engine drags a SPA edit. That also conflicts with the repo's general
-style (no magic strings; signals expressed as types/catalogs on the backend).
-
-## Considered Options
-
-- **A. Hardcode on the frontend.** The SPA builds the clashmi deeplink from `sub.url` itself and
-  knows the titles. Cons: a direct violation of the requirement; the deeplink format and the link
-  list live in JS; every new client = a frontend edit; duplicated escaping logic.
-- **B. `sub.url` + a parallel `deeplinks` field.** Keep the URL, add a list of deeplinks beside it.
-  Cons: the frontend still knows the shape of each special field; not uniform; adding a link kind
-  isn't catalog-driven — again contract and frontend edits.
-- **C. A flat `sub.links: [{title, value}]` list, the catalog in a backend service (chosen).** The
-  response carries a ready, ordered list of copyable "title → value" pairs; the frontend renders it
-  as is. The catalog (which links, their titles, the deeplink format) lives in a new
-  `internal/service/sublinks`.
-- Source of the clashmi deeplink's `name`: **(i) the profile title of the effective config (chosen)**,
-  (ii) a separate service env field, (iii) the user's nickname. (i) matches semantically what the
-  subscription already returns in the `Profile-Title` header and adds no new configuration.
-
-## Decision
-
-Option **C** was chosen. A new `internal/service/sublinks` service owns an ordered catalog
-`[]linkSpec{ title, kind, build(subURL, profileTitle) }`: for Mihomo `build` is the identity (the
-URL itself), for Clashmi it is the deeplink format with `url.QueryEscape`. `Links(users)` builds
-each user's URL (`base + /sub/<kind>/<token>`) and, for deeplinks, substitutes `name` = the profile
-title of the user's **effective** config (custom, else base). Title resolution is efficient: the
-base title is read once per engine, custom ones only for users who have them.
-
-The `sub` contract in `GET /admin/api/users` changes from `{id, url}` to `{links: [{title, value}]}`
-(`id`/`url` removed — `id` was unused by the frontend, `url` is replaced by the list). The
-`users_get` handler delegates assembly to the service and no longer builds the URL itself.
-
-## Consequences
-
-- **Adding an engine/app = one line in the `catalog`** — no frontend, contract, or admin-API edits.
-  The frontend renders `sub.links` verbatim (title + a "Copy" button).
-- `sub.id`/`sub.url` are gone from the response. apitest (black box) selects the "raw" subscription
-  URL by scheme (`http…`), not by title (`UserSub.SubURL()`), staying agnostic to the link set.
-- Title resolution per page is several reads (base + customs), not one-per-user; for an admin page
-  that is unnoticeable.
-- Today the catalog is tied to mihomo (the Clashmi deeplink is a Clash client; `sublinks` imports
-  `mihomo.Profile` for the title). This is deliberate: when xray/sing-box are added, the catalog and
-  its dependencies expand explicitly, without hidden "magic".
diff --git a/docs/decisions/0009-public-ready-and-english-docs.md b/docs/decisions/0009-public-ready-and-english-docs.md
deleted file mode 100644
index cf11c3e..0000000
--- a/docs/decisions/0009-public-ready-and-english-docs.md
+++ /dev/null
@@ -1,55 +0,0 @@
-# 0009 — Public-ready: English-only docs & UI, MIT license
-
-- **Status:** Accepted
-- **Date:** 2026-06-18
-- **PR:** #TBD
-
-## Context
-
-subgen is being published as a public repository. Two project-level decisions had to be
-made and recorded so future contributors share the same defaults:
-
-1. **Language.** Human-facing text was inconsistent: `README.md` and `docs/subgen.md` were
-   English, while `CHANGELOG.md`, the ADRs, `AGENTS.md`, the admin UI labels and the
-   user-facing handler messages were Russian. A public repo needs one language.
-2. **License.** There was no `LICENSE` file. Without one the code is, by default, "all
-   rights reserved" — not open-source; nobody may legally fork or reuse it.
-
-## Considered Options
-
-- **Language**
-  - **English everywhere** — docs, ADRs, `AGENTS.md`, `CHANGELOG`, admin UI, user-facing
-    messages. Widest reach for an open-source audience; one language to maintain.
-  - **Russian everywhere** — matches the original UI/market, but narrows the contributor
-    and user base for a public project.
-  - **Bilingual** (e.g. `README.md` + `README.ru.md`) — broadest, but double the
-    maintenance and easy to let drift.
-- **License**
-  - **MIT** — short, maximally permissive, by far the most common; reuse with attribution.
-  - **Apache-2.0** — permissive plus an explicit patent grant; more ceremony.
-  - **GPL-3.0** — copyleft; forks must stay open.
-  - **None** — remain proprietary.
-
-## Decision
-
-**English for all human-facing text** (docs, ADRs, `AGENTS.md`, `CHANGELOG`, admin UI
-labels, and user-facing handler/error messages), and the **MIT** license.
-
-English maximizes reach and keeps a single source of truth without the drift risk of a
-bilingual setup. MIT is the lowest-friction choice for a small self-hosted tool we want
-people to freely run and fork; the patent and copyleft concerns of Apache/GPL do not apply
-here.
-
-## Consequences
-
-- A one-time sweep translated `AGENTS.md`, `CHANGELOG.md`, every ADR, `apitest/README.md`,
-  `docs/subgen.md`, the admin SPA (`internal/handlers/web/static/`), and all user-facing
-  message constants in `internal/handlers/*` to English. Unit tests and the black-box
-  `apitest` assertions were updated in lockstep (they assert the exact text).
-- New code and docs must stay English — including user-facing strings. This is the standing
-  rule; `CONTRIBUTING.md` states it, and a `grep -I '[А-Яа-я]'` over the tree should stay
-  empty (operator-entered data in the running store is exempt).
-- A `LICENSE` (MIT) is added; GitHub now recognises the project as MIT-licensed, and the
-  `README` carries the badge and a license section.
-- The product can still serve Russian-market users; only the codebase, UI chrome and docs
-  are English.
diff --git a/internal/entity/validation_errors.go b/internal/entity/validation_errors.go
index c7b0236..eaa49e0 100644
--- a/internal/entity/validation_errors.go
+++ b/internal/entity/validation_errors.go
@@ -3,7 +3,7 @@ package entity
 import "errors"
 
 // Node validation sentinels — node/inbound input validation moved out of the handler into
-// the nodes service (see docs/decisions/0003-validation-in-code.md). The service returns
+// the nodes service (value validation lives in the service layer — see AGENTS.md). The service returns
 // these; the handler maps each to a user-facing 400 message (constant by handler). They
 // carry no interpolated values — the offending field is known at the call site.
 var (
diff --git a/openspec/changes/.gitkeep b/openspec/changes/.gitkeep
new file mode 100644
index 0000000..bffcef6
--- /dev/null
+++ b/openspec/changes/.gitkeep
@@ -0,0 +1 @@
+# Active OpenSpec changes live here (one directory per change). Empty until the first proposal.
diff --git a/openspec/changes/archive/.gitkeep b/openspec/changes/archive/.gitkeep
new file mode 100644
index 0000000..d2a41b0
--- /dev/null
+++ b/openspec/changes/archive/.gitkeep
@@ -0,0 +1 @@
+# Archived OpenSpec changes live here after they are applied and archived.
diff --git a/openspec/changes/archive/2026-06-28-adopt-openspec/design.md b/openspec/changes/archive/2026-06-28-adopt-openspec/design.md
new file mode 100644
index 0000000..b8b1429
--- /dev/null
+++ b/openspec/changes/archive/2026-06-28-adopt-openspec/design.md
@@ -0,0 +1,49 @@
+# Design — adopt OpenSpec, retire ADRs
+
+## Context
+
+The project recorded design decisions as ADRs (`docs/decisions/0001–0009`) plus a per-PR
+`CHANGELOG.md` (the convention codified in ADR-0001). ADRs capture *point-in-time decisions*, but
+there was no maintained, machine-checkable description of the as-built behavior; it stayed
+implicit across code, docs and tests. [OpenSpec](https://github.com/Fission-AI/OpenSpec) (the
+`spec-driven` schema) provides a living behavior contract plus a structured change workflow
+(`proposal` / `design` / `tasks` + spec deltas), with slash commands and a validating CLI.
+
+## Goals / Non-Goals
+
+**Goals:**
+- One forward process for non-trivial changes, with a living spec baseline.
+- Keep the per-PR `CHANGELOG`.
+- Make the workflow reproducible for every contributor (tracked, not local-only).
+
+**Non-Goals:**
+- No Go behavior change.
+- Not re-homing every historical ADR as a retroactive change (git history keeps them).
+
+## Considered Options
+
+- **Keep ADRs only.** Familiar, zero new tooling, but no living behavior spec; the as-built
+  contract stays implicit and scattered.
+- **Adopt OpenSpec alongside ADRs.** Both a decision catalog and a spec workflow — but two
+  overlapping processes invite confusion and duplicate the rationale.
+- **Adopt OpenSpec and retire ADRs (chosen).** One forward process; the rationale that ADRs held
+  now lives in each change's `design.md`; the `CHANGELOG` stays. `docs/decisions/` is removed (the
+  records remain in git history).
+
+## Decision
+
+Adopt OpenSpec as the planning and change-documentation process and **retire the ADR process**.
+Seed a full spec baseline under `openspec/specs/`. Record this migration as this archived OpenSpec
+change rather than a final ADR. Remove `docs/decisions/`; rely on git history for the old records.
+
+## Consequences
+
+- The `/opsx:*` commands and skills are generated under `.claude/`; the `.claude` gitignore is
+  narrowed so they are tracked (reproducible for contributors, CI, and review). Contributors not
+  using Claude run the same flow with the `openspec` CLI (`npx @fission-ai/openspec`).
+- `openspec/specs/` is the living behavior contract, validated by
+  `openspec validate --specs --strict`. Keeping it in sync becomes part of the per-change
+  checklist.
+- The English-only rule applies to all OpenSpec artifacts (the standing grep guard stays empty).
+- Inline ADR citations in the docs and a few code comments are dropped or repointed; their
+  decisions are preserved in git history and, where they describe behavior, in the specs.
diff --git a/openspec/changes/archive/2026-06-28-adopt-openspec/proposal.md b/openspec/changes/archive/2026-06-28-adopt-openspec/proposal.md
new file mode 100644
index 0000000..b3b1afb
--- /dev/null
+++ b/openspec/changes/archive/2026-06-28-adopt-openspec/proposal.md
@@ -0,0 +1,32 @@
+# Adopt OpenSpec; retire the ADR process
+
+## Why
+
+Design decisions were recorded as ADRs (`docs/decisions/0001–0009`) plus a per-PR `CHANGELOG.md`.
+ADRs capture point-in-time decisions well, but the project grew subsystems with real behavioral
+contracts — routing, config ownership, cross-panel provisioning, subscription rendering — and
+there was no maintained, machine-checkable description of *what the system currently does*. We
+want a structured, AI-native, spec-driven workflow that keeps a living behavior contract
+alongside the decision trail, with first-class tooling.
+
+## What Changes
+
+- Adopt [OpenSpec](https://github.com/Fission-AI/OpenSpec) (the `spec-driven` schema) as the
+  planning and change-documentation process.
+- Seed a full spec baseline under `openspec/specs/<capability>/spec.md` (12 capabilities) from the
+  current code, in the requirement + WHEN/THEN scenario format.
+- Add the `/opsx:*` workflow under `.claude/` and narrow the blanket `.claude` gitignore to
+  `.claude/settings.local.json` so the commands/skills are tracked.
+- Rewrite the process in `AGENTS.md`, `CONTRIBUTING.md`, `README.md`, and the `CHANGELOG.md`
+  header to point at OpenSpec.
+- **Remove the `docs/decisions/` ADR catalog** (the records remain in git history). The
+  `CHANGELOG` stays; non-trivial changes now link an archived OpenSpec change.
+
+## Impact
+
+- `openspec/` — new spec baseline, config, and change workflow.
+- `.claude/` — `/opsx:*` commands and skills (now tracked).
+- `.gitignore`, `AGENTS.md`, `CONTRIBUTING.md`, `README.md`, `CHANGELOG.md` — process pointers.
+- `docs/decisions/` — removed. Inline ADR citations across the docs and a few code comments are
+  dropped or repointed.
+- No Go behavior changes.
diff --git a/openspec/changes/archive/2026-06-28-adopt-openspec/tasks.md b/openspec/changes/archive/2026-06-28-adopt-openspec/tasks.md
new file mode 100644
index 0000000..895f4b3
--- /dev/null
+++ b/openspec/changes/archive/2026-06-28-adopt-openspec/tasks.md
@@ -0,0 +1,13 @@
+# Tasks — adopt OpenSpec, retire ADRs
+
+- [x] Scaffold OpenSpec (`openspec init --tools claude`): `config.yaml`, `specs/`, `changes/`.
+- [x] Fill `openspec/config.yaml` with the project context and per-artifact rules.
+- [x] Narrow the `.claude` gitignore to `.claude/settings.local.json` so `/opsx:*` is tracked.
+- [x] Write the full spec baseline under `openspec/specs/` (12 capabilities); validate with
+      `openspec validate --specs --strict`.
+- [x] Rewrite the process in `AGENTS.md`, `CONTRIBUTING.md`, `README.md`, and the `CHANGELOG.md`
+      header to point at OpenSpec.
+- [x] Remove the `docs/decisions/` ADR catalog; drop or repoint inline ADR citations across the
+      docs and code comments.
+- [x] Record this migration as an archived OpenSpec change.
+- [x] Add the `CHANGELOG.md` entry.
diff --git a/openspec/config.yaml b/openspec/config.yaml
new file mode 100644
index 0000000..c17fdf2
--- /dev/null
+++ b/openspec/config.yaml
@@ -0,0 +1,60 @@
+schema: spec-driven
+
+# Project context — shown to the AI when creating artifacts.
+context: |
+  subgen is a standalone mihomo/Clash.Meta subscription server (Go). It provisions
+  VLESS clients on a fleet of 3x-ui panels and renders per-subscriber mihomo configs.
+
+  Authority: AGENTS.md is the single source of truth for code style and architecture.
+  Always read it before proposing or designing a change. The design doc is docs/subgen.md.
+
+  Tech stack:
+  - Go service; HTTP contract described in OpenAPI (openapi/), handlers generated by ogen
+    (internal/oas). Add/change an endpoint by editing the spec, then `go generate`, then a
+    handler against the generated interface. Routes are never registered by hand.
+  - SQLite store (modernc) with an ordered migration runner (migrations.Apply: 0001 baseline
+    + NNNN-*.sql by name, tracked in schema_migrations, forward-only, pure DDL).
+  - External 3x-ui panels via internal/clients/xui (thin DTO->domain adapter, Bearer token).
+  - Frontend: a minimal Vue 3 SPA (no bundler) in internal/handlers/web/static.
+
+  Architecture (hard rules — see AGENTS.md "Target rules"):
+  - Layers flow bottom-up: repository|clients -> service -> handler. The lower layer never
+    knows the upper one. No `App` oracle; composition is in cmd/service/main.go.
+  - One package per action (internal/handlers/<action>) / per entity repository.
+  - Dependencies are private interfaces in a per-package contract.go + mockgen mocks,
+    named after the concrete dependency (usersRepo, fleetService, panelClient).
+  - Strong-typed entity: typed constants over magic strings; entity references by numeric id,
+    never by name/port; string-content comparison is forbidden.
+  - Errors are sentinel constants in entity (no interpolation). Lower layers wrap technical
+    errors; the handler classifies by sentinel: domain -> typed 4xx with a local message
+    constant (slog.Warn); infrastructure -> 5xx (slog.Error). A DB error is never a 400.
+  - Value validation lives in the service layer (sentinel errors), not in the OpenAPI schema.
+  - Uniqueness is caught from the DB constraint code (repository/dberr), not pre-check SELECTs.
+
+  Conventions:
+  - English only, everywhere in the repo — no Cyrillic anywhere in the tree (the AGENTS.md
+    grep guard must stay empty). The single exception is operator-entered data in the store.
+  - Tests are strict table-driven (testify require/assert + gomock), one Test{Type}_{Method}
+    per method. Integration tests live in apitest/ (black-box, build tag `apitest`).
+  - Every PR adds one CHANGELOG.md entry (`## YYYY-MM-DD — <title> (#PR)`, reverse-chrono,
+    no version sections).
+  - Work happens in a git worktree on its own branch -> PR (never edit main directly).
+
+  Planning process: design decisions are recorded as OpenSpec changes (this directory).
+  This replaces the former ADR process (the docs/decisions/ catalog was removed).
+
+# Per-artifact rules — constraints applied when generating each artifact type.
+rules:
+  proposal:
+    - Write in English. Keep it tight — Why / What Changes / Impact.
+    - Read AGENTS.md first; the change must fit the existing layered architecture.
+  specs:
+    - Write in English. Each requirement text contains SHALL or MUST.
+    - Every requirement has at least one #### Scenario with WHEN / THEN (/ AND) steps.
+    - Describe observable behavior and invariants, not implementation details.
+  design:
+    - Write in English. Justify the choice and the trade-off, like the old ADRs did
+      (Context / Considered Options / Decision / Consequences is a good shape).
+    - Respect the hard rules in AGENTS.md (layering, sentinel errors, no magic strings).
+  tasks:
+    - Write in English. Order tasks so each leaves the build green (go build/vet, tests).
diff --git a/openspec/specs/admin-auth/spec.md b/openspec/specs/admin-auth/spec.md
new file mode 100644
index 0000000..a30811d
--- /dev/null
+++ b/openspec/specs/admin-auth/spec.md
@@ -0,0 +1,119 @@
+# Admin Authentication Spec
+
+## Purpose
+
+Gate the admin surface behind a single shared password. The admin panel is always on
+(`SUBGEN_ADMIN_PASSWORD` is mandatory). A successful login mints a stateless, HMAC-signed
+session cookie (`subgen_admin`); the cookie alone authorizes the JSON admin API and the SPA
+pages — there is no server-side session store. Browser pages redirect when unauthenticated;
+the JSON API answers `401`.
+
+## Requirements
+
+### Requirement: Session cookie format and lifetime
+
+The session cookie `subgen_admin` SHALL be a stateless `<expiry-unix>.<hmac-sha256-hex>` value
+signed with the configured secret, valid for 12 hours, and set with `HttpOnly`, `Secure`, and
+`SameSite=Lax`.
+
+#### Scenario: Cookie issued on login
+
+- **WHEN** a login succeeds
+- **THEN** a `subgen_admin` cookie is set whose value is `<expiry>.<hmac>` over the expiry
+- **AND** the cookie is marked `HttpOnly`, `Secure`, `SameSite=Lax`, with a 12-hour max age
+
+#### Scenario: Expired cookie is not valid
+
+- **WHEN** a request presents a `subgen_admin` cookie whose expiry is in the past
+- **THEN** the cookie is treated as invalid (the session is not authorized)
+
+#### Scenario: Tampered cookie is rejected
+
+- **WHEN** a request presents a `subgen_admin` cookie whose HMAC does not match its expiry
+- **THEN** the cookie is treated as invalid (constant-time comparison, no partial trust)
+
+### Requirement: Login
+
+`POST /admin/api/login` SHALL accept a username and password, and MUST issue a session cookie
+only when both match the configured admin credentials, comparing them in constant time.
+
+#### Scenario: Valid credentials
+
+- **WHEN** `POST /admin/api/login` is called with the correct username and password
+- **THEN** the response is `200` with `{ "message": ... }`
+- **AND** a valid `subgen_admin` session cookie is set
+
+#### Scenario: Invalid credentials
+
+- **WHEN** `POST /admin/api/login` is called with a wrong username or password
+- **THEN** the response is `401` with `{ "errMessage": "Invalid username or password" }`
+- **AND** no session cookie is set
+- **AND** the comparison does not reveal whether the username or the password was wrong
+
+### Requirement: Logout
+
+`POST /admin/api/logout` SHALL clear the session cookie and always succeed.
+
+#### Scenario: Logout clears the session
+
+- **WHEN** `POST /admin/api/logout` is called
+- **THEN** the response is `204` with no body
+- **AND** the `subgen_admin` cookie is expired (cleared) on the client
+
+### Requirement: Admin JSON API gate
+
+Every `/admin/api/*` endpoint except login SHALL require a valid session cookie, returning
+`401` when it is missing or invalid.
+
+#### Scenario: Missing session on a protected endpoint
+
+- **WHEN** an `/admin/api/*` endpoint (other than login) is called without a valid session cookie
+- **THEN** the response is `401` with `{ "errMessage": "Authorization required" }`
+
+#### Scenario: Valid session passes the gate
+
+- **WHEN** a protected `/admin/api/*` endpoint is called with a valid session cookie
+- **THEN** the request reaches its handler and is served normally
+
+### Requirement: SPA page gating and redirects
+
+The admin browser pages SHALL redirect based on session state instead of returning `401`:
+unauthenticated visits to the app are sent to the login page, and an authenticated visit to the
+login page is sent to the app.
+
+#### Scenario: Unauthenticated app shell
+
+- **WHEN** `GET /admin` or `GET /admin/{view}` is requested without a valid session
+- **THEN** the response is `302` to `/admin/login`
+
+#### Scenario: Authenticated app shell
+
+- **WHEN** `GET /admin` or `GET /admin/{view}` is requested with a valid session
+- **THEN** the response is `200` serving the SPA shell HTML
+
+#### Scenario: Login page while already signed in
+
+- **WHEN** `GET /admin/login` is requested with a valid session
+- **THEN** the response is `302` to the app
+
+#### Scenario: Login page while signed out
+
+- **WHEN** `GET /admin/login` is requested without a valid session
+- **THEN** the response is `200` serving the login page HTML
+
+### Requirement: Central request-decoding errors
+
+Requests that fail security or body/parameter decoding before reaching a handler SHALL be
+answered by the central error handler: security failures as `401` and malformed
+requests as `400`, without leaking internal detail.
+
+#### Scenario: Malformed request body
+
+- **WHEN** a request body or parameter cannot be decoded by the generated router
+- **THEN** the response is `400` with `{ "errMessage": "Bad request" }`
+
+#### Scenario: Security failure logged once
+
+- **WHEN** a security check fails before the handler runs
+- **THEN** the central error handler returns `401` and logs the event at warn level
+- **AND** it does not re-log errors that handlers already logged with their own context
diff --git a/openspec/specs/admin-users/spec.md b/openspec/specs/admin-users/spec.md
new file mode 100644
index 0000000..d2ffd6d
--- /dev/null
+++ b/openspec/specs/admin-users/spec.md
@@ -0,0 +1,133 @@
+# Admin Users Spec
+
+## Purpose
+
+The admin-facing management of subscription users: listing with filters and pagination,
+creating, editing, deleting, and recreating users, plus exposing each user's ready-to-use
+subscription links. Value validation lives in the service and surfaces as typed `4xx`
+responses; uniqueness conflicts surface as `409`. This capability owns the HTTP contract;
+the cross-panel client lifecycle it triggers is specified in `user-provisioning`.
+
+## Requirements
+
+### Requirement: List users with filters and pagination
+
+`GET /admin/api/users` SHALL return a page of users with their connections and subscription
+links, and MUST clamp pagination to safe bounds.
+
+#### Scenario: Default page
+
+- **WHEN** `GET /admin/api/users` is called without pagination parameters
+- **THEN** the response is `200` with `{ users, total, page, perPage }`
+- **AND** `page` defaults to 1 and `perPage` defaults to 50
+
+#### Scenario: Pagination clamping
+
+- **WHEN** `perPage` is greater than 200, or `page`/`perPage` is below 1
+- **THEN** `perPage` is clamped to at most 200, `page` below 1 becomes 1, and `perPage` below 1 becomes 50
+
+#### Scenario: Text filter
+
+- **WHEN** the `q` query parameter is provided
+- **THEN** only users whose name matches the substring are returned
+
+#### Scenario: Inbound filter is OR-matched
+
+- **WHEN** the `inbound` parameter lists one or more inbound ids
+- **THEN** a user is included if it is bound to at least one of those inbounds
+
+#### Scenario: Each user carries connections and links
+
+- **WHEN** a user is returned
+- **THEN** it includes its `inbounds` (each with `id`, `label`, `port`, and a `missing` flag)
+- **AND** it includes a `sub.links` array and traffic `stats`
+
+### Requirement: Create user
+
+`POST /admin/api/users/create` SHALL create a user from a name, an optional description, and a
+set of inbound ids, validating the input in the service and mapping each domain error to a typed
+`4xx`.
+
+#### Scenario: Successful creation
+
+- **WHEN** a valid name, optional description, and at least one existing inbound id are submitted
+- **THEN** the response is `200` with a success message
+- **AND** the user is provisioned across the selected inbounds' panels
+
+#### Scenario: Invalid name
+
+- **WHEN** the name does not match the allowed format (lowercase letters, digits, `_`, `-`, 1–32 chars)
+- **THEN** the response is `400` reporting an invalid name (`entity.ErrInvalidUserName`)
+
+#### Scenario: No connection selected
+
+- **WHEN** the inbound id list is empty
+- **THEN** the response is `400` reporting that at least one connection is required (`entity.ErrNoConnectionSelected`)
+
+#### Scenario: Description too long
+
+- **WHEN** the description exceeds 500 characters
+- **THEN** the response is `400` reporting the description is too long (`entity.ErrDescriptionTooLong`)
+
+#### Scenario: Unknown inbound or node
+
+- **WHEN** an inbound id (or its node) does not exist
+- **THEN** the response is `400` reporting the missing inbound/node (`entity.ErrInboundNotFound` / `entity.ErrNodeNotFound`)
+
+#### Scenario: Name already taken
+
+- **WHEN** the name collides with an existing user
+- **THEN** the response is `409` reporting the name is taken (`entity.ErrNameTaken`)
+
+#### Scenario: Email already present on a panel
+
+- **WHEN** a panel already holds a client with the same email (nickname)
+- **THEN** the response is `409` reporting the panel collision (`entity.PanelClientExistsError`, naming the node)
+
+### Requirement: Edit user
+
+`POST /admin/api/users/edit` SHALL replace a user's inbound set and description, applying the
+same validation as creation and re-binding the user across panels.
+
+#### Scenario: Successful edit
+
+- **WHEN** an existing user id, a non-empty set of existing inbound ids, and an optional description are submitted
+- **THEN** the response is `200` with a success message
+- **AND** the user's connections and description are updated and panels re-bound
+
+#### Scenario: Edit validation mirrors create
+
+- **WHEN** the new inbound set is empty, the description is too long, or an inbound does not exist
+- **THEN** the response is `400` with the corresponding validation error
+
+### Requirement: Delete user
+
+`POST /admin/api/users/delete` SHALL remove a user and best-effort remove its panel clients.
+
+#### Scenario: Successful deletion
+
+- **WHEN** an existing user id is submitted
+- **THEN** the response is `200` with a success message
+- **AND** the user's clients are removed from its panels where reachable, and the user row is deleted
+
+### Requirement: Recreate user clients
+
+`POST /admin/api/users/recreate` SHALL re-provision a user's panel clients from the stored
+connections, to repair drift.
+
+#### Scenario: Successful recreate
+
+- **WHEN** an existing user id is submitted
+- **THEN** the response is `200` with a success message
+- **AND** the user's clients are re-bound on all its panels from the stored connection set
+
+### Requirement: Subscription links are backend-owned
+
+Each user's `sub.links` SHALL be produced by the backend link catalog as ordered
+`{ title, value }` pairs, so the frontend renders them verbatim without hardcoding any link.
+
+#### Scenario: Links rendered from the catalog
+
+- **WHEN** a user is listed
+- **THEN** `sub.links` contains one entry per catalog link, each with a `title` and a `value` URL/deeplink
+- **AND** the titles and formats come from the backend, not the client
diff --git a/openspec/specs/config-ownership/spec.md b/openspec/specs/config-ownership/spec.md
new file mode 100644
index 0000000..83f26ef
--- /dev/null
+++ b/openspec/specs/config-ownership/spec.md
@@ -0,0 +1,65 @@
+# Config Ownership Spec
+
+## Purpose
+
+Who owns a subscription config, independent of which engine renders it. A single anchor table
+`subscription_configs(id, user_id, kind, created_at)` records ownership: `user_id NULL` is the
+base config shared by everyone, a non-null `user_id` is that user's personal custom. `kind` is a
+typed `entity.ConfigKind` (the engine — `mihomo` today, later xray/sing-box), never a magic
+string. Each kind has one base plus at most one custom per user. The engine's content hangs off
+the anchor by `config_id`; the anchor itself knows nothing about mihomo. A custom is a snapshot —
+once cloned it is independent of the base.
+
+## Requirements
+
+### Requirement: Base and per-user custom per kind
+
+The anchor SHALL hold exactly one base config (`user_id NULL`) per kind and at most one custom
+config per user per kind, enforced by a unique index over `(COALESCE(user_id,0), kind)`.
+
+#### Scenario: One base per kind
+
+- **WHEN** configs exist for a kind
+- **THEN** there is a single base config (`user_id NULL`) for that kind
+
+#### Scenario: At most one custom per user per kind
+
+- **WHEN** a user already has a custom config for a kind
+- **THEN** attempting to create a second one for the same user and kind is rejected by the unique index
+
+### Requirement: Typed config kind
+
+A config's engine SHALL be a typed `entity.ConfigKind` constant, validated against the supported
+kinds rather than compared as a string.
+
+#### Scenario: Unsupported kind
+
+- **WHEN** an operation targets a kind that is not registered/supported
+- **THEN** it is rejected as an unknown kind (no string matching)
+
+### Requirement: Custom is an independent snapshot
+
+Creating a custom config SHALL clone the base content into the new config so the custom is
+independent — later edits to the base do not reach existing customs, in one transaction with the
+anchor row.
+
+#### Scenario: Edits to base do not leak into a custom
+
+- **WHEN** a custom is created from the base and the base is later edited
+- **THEN** the custom keeps its cloned content unchanged
+
+#### Scenario: Clone from an empty base
+
+- **WHEN** a custom is created while the base has no content
+- **THEN** the custom is created empty (nothing to copy) and is still independent
+
+### Requirement: Atomic content save scoped by config
+
+Saving engine content SHALL replace all of that config's content atomically, scoped to its
+`config_id`, so a failed save leaves the previous content intact.
+
+#### Scenario: All-or-nothing save
+
+- **WHEN** a content save runs for a config
+- **THEN** the config's groups, members, rules, and providers are replaced in a single transaction
+- **AND** if any step fails, nothing is recorded for that config
diff --git a/openspec/specs/database-migrations/spec.md b/openspec/specs/database-migrations/spec.md
new file mode 100644
index 0000000..27f9293
--- /dev/null
+++ b/openspec/specs/database-migrations/spec.md
@@ -0,0 +1,62 @@
+# Database Migrations Spec
+
+## Purpose
+
+The SQLite store evolves through an ordered, forward-only migration runner invoked on startup.
+Files are `NNNN-*.sql`, so a plain name sort is the apply order: `0001-init.sql` is the immutable
+baseline (`CREATE … IF NOT EXISTS`), later files add changes. Each file is applied exactly once,
+tracked in `schema_migrations`, in its own transaction; on error the service crashes rather than
+running on a half-migrated schema. Migrations are pure DDL — connection PRAGMAs live in the DSN.
+Constraint violations surface to the repositories as typed codes, never string matches.
+
+## Requirements
+
+### Requirement: Ordered, apply-once migrations
+
+The runner SHALL apply each migration file exactly once, in filename order, tracking applied
+files in `schema_migrations`, and MUST skip already-applied files on restart.
+
+#### Scenario: Fresh database
+
+- **WHEN** the runner starts against an empty database
+- **THEN** every migration is applied in name order and recorded in `schema_migrations`
+
+#### Scenario: Restart
+
+- **WHEN** the runner starts against a database where some migrations are already recorded
+- **THEN** only the not-yet-applied files run, in order
+
+#### Scenario: New schema change
+
+- **WHEN** a structural schema change is needed
+- **THEN** it is added as a new `NNNN-*.sql` file rather than by editing the baseline
+
+### Requirement: Transactional, forward-only, crash on error
+
+The runner SHALL apply each migration atomically and MUST abort startup on failure; there are no
+rollbacks.
+
+#### Scenario: Migration fails
+
+- **WHEN** a migration errors mid-apply
+- **THEN** its transaction is rolled back, it is not recorded, and startup fails (the service crashes)
+
+#### Scenario: Non-transactional rebuild
+
+- **WHEN** a migration must rebuild a table outside a transaction (e.g. toggling a connection PRAGMA)
+- **THEN** it uses the dedicated non-transactional mode and records itself
+
+### Requirement: Constraint violations map to domain sentinels
+
+Repositories SHALL detect uniqueness and foreign-key violations by the driver's extended result
+code, never by error text, and translate them to domain sentinel errors.
+
+#### Scenario: Unique or primary-key violation
+
+- **WHEN** an insert/update violates a unique or primary-key constraint (code 2067 or 1555)
+- **THEN** the repository returns the corresponding domain sentinel (e.g. `entity.ErrNameTaken`, `entity.ErrNodeNameTaken`, `entity.ErrRuleProviderNameTaken`)
+
+#### Scenario: Foreign-key violation
+
+- **WHEN** a delete violates a foreign-key constraint (code 787)
+- **THEN** the repository returns `entity.ErrInboundReferenced`
diff --git a/openspec/specs/fleet/spec.md b/openspec/specs/fleet/spec.md
new file mode 100644
index 0000000..7f4068c
--- /dev/null
+++ b/openspec/specs/fleet/spec.md
@@ -0,0 +1,72 @@
+# Fleet Assembly Spec
+
+## Purpose
+
+The live view of the fleet, built fresh from the panels (no global snapshot). For each node the
+service lists the panel's inbounds, matches them to configured inbounds by port, and collects the
+enabled clients into per-subscriber proxy sets keyed by `subId`. Configuration data flows
+bottom-up on every request; one unreachable panel is tolerated so a single bad node does not take
+down subscriptions for everyone.
+
+## Requirements
+
+### Requirement: Match configured inbounds to panel inbounds by port
+
+Fleet assembly SHALL resolve each configured inbound against the panel by its port, since the
+port is the identifier on the 3x-ui side.
+
+#### Scenario: Port match
+
+- **WHEN** a configured inbound's port exists on its panel
+- **THEN** that panel inbound's stream settings and clients are used for the inbound
+
+#### Scenario: Configured inbound absent on panel
+
+- **WHEN** a configured inbound's port is not present on the panel
+- **THEN** the inbound is treated as observed-empty and contributes no proxies
+
+### Requirement: Tolerate a single unreachable panel
+
+Fleet assembly SHALL skip a panel that cannot be reached (with a log) and MUST fail only when no
+panel can be reached.
+
+#### Scenario: One panel down
+
+- **WHEN** one node's panel cannot be listed but others can
+- **THEN** the fleet is built from the reachable panels and the failed one is skipped
+
+#### Scenario: All panels down
+
+- **WHEN** no panel can be reached
+- **THEN** fleet assembly returns an error
+
+### Requirement: Build per-subscriber proxies from enabled clients
+
+Fleet assembly SHALL produce one proxy per enabled client per inbound it appears on, grouped into
+a subscriber by `subId`, with the proxy named by the inbound label.
+
+#### Scenario: Enabled client becomes a proxy
+
+- **WHEN** an enabled client with a `subId` is present on an enabled inbound
+- **THEN** a proxy is created for it under that inbound, named `<node>-<inbound>`, carrying the client's uuid/flow and stream settings
+- **AND** the proxy is grouped under the subscriber identified by the client's `subId`
+
+#### Scenario: Disabled inbound yields no proxies
+
+- **WHEN** a panel inbound is disabled
+- **THEN** no proxies are produced from it
+
+### Requirement: Distinguish observed-empty from missing inbound
+
+Fleet assembly SHALL record which clients are present per inbound such that an inbound observed
+with no clients is distinct from an inbound that is missing on the panel.
+
+#### Scenario: Observed-empty inbound
+
+- **WHEN** an inbound exists on the panel but has no matching clients
+- **THEN** its client set is recorded as empty (present but empty)
+
+#### Scenario: Missing inbound
+
+- **WHEN** an inbound is not present on the panel at all
+- **THEN** it has no client-set entry (distinct from an empty set)
diff --git a/openspec/specs/mihomo-config/spec.md b/openspec/specs/mihomo-config/spec.md
new file mode 100644
index 0000000..d747bf9
--- /dev/null
+++ b/openspec/specs/mihomo-config/spec.md
@@ -0,0 +1,157 @@
+# Mihomo Config Spec
+
+## Purpose
+
+The routing configuration domain for the mihomo engine: proxy groups, routing rules (including
+recursive logical rules), rule providers, a base YAML preamble, and profile metadata. The model
+is strongly typed — routing targets and group members are a single typed `PolicyRef`
+(`direct`/`reject`/…/`inbound`/`group`), never a magic string. The config is decoded and
+validated in `internal/mihomo` with sentinel errors; the admin handler maps each sentinel to a
+typed `400` with a local message. Group references cross the HTTP boundary by array index, not
+database id. The admin endpoints read, save, list, create, and delete configs, and probe a rule
+provider.
+
+## Requirements
+
+### Requirement: Typed policy references and catalogs
+
+The config model SHALL resolve routing targets and group members through a typed `PolicyRef`
+(kind plus optional inbound/group id) and MUST expose the reference taxonomy via a schema
+endpoint so the frontend hardcodes nothing.
+
+#### Scenario: Schema catalog served
+
+- **WHEN** `GET /admin/api/config/mihomo/schema` is called
+- **THEN** the response is `200` describing `actions`, `ruleProvider` behaviors/formats, `proxyGroup` types (with allowed member categories), `rules` types (with allowed destination categories and per-type flags), and `generatedKeys`
+- **AND** option lists are sorted by name
+
+#### Scenario: Exactly one reference mode per PolicyRef
+
+- **WHEN** a `PolicyRef` is validated
+- **THEN** a built-in kind carries no inbound/group id, an inbound kind carries only an inbound id, and a group kind carries only a group index
+
+### Requirement: Read effective config
+
+`GET /admin/api/config/mihomo` SHALL return the base config when no user scope is given, the
+user's custom config when `?user=<id>` is given, and `404` when that user has no custom config.
+
+#### Scenario: Read base
+
+- **WHEN** `GET /admin/api/config/mihomo` is called without `user`
+- **THEN** the response is `200` with the base config (an empty config if none was ever saved)
+
+#### Scenario: Read existing custom
+
+- **WHEN** `GET /admin/api/config/mihomo?user=<id>` is called for a user that has a custom config
+- **THEN** the response is `200` with that user's custom config
+
+#### Scenario: Read missing custom
+
+- **WHEN** `GET /admin/api/config/mihomo?user=<id>` is called for a user with no custom config
+- **THEN** the response is `404`
+
+### Requirement: Save config with full validation
+
+`POST /admin/api/config/mihomo/save` SHALL decode and validate the whole config and persist it
+atomically, mapping any validation failure to a `400` with a specific message; an absent `userId`
+targets the base config and a positive `userId` targets that user's custom config.
+
+#### Scenario: Save base
+
+- **WHEN** a valid config is posted with no `userId`
+- **THEN** the response is `200` and the base config is replaced atomically
+
+#### Scenario: Save custom requires an existing custom
+
+- **WHEN** a config is posted with a positive `userId` for a user that has no custom config
+- **THEN** the response is `400` reporting the user has no custom config (`entity.ErrUserConfigNotFound`)
+
+#### Scenario: Proxy-group validation
+
+- **WHEN** a group has an empty or duplicate name, an unknown type, no members, a field not allowed for its type, or the groups form a cycle
+- **THEN** the response is `400` reporting that specific group error
+
+#### Scenario: Routing-rule validation
+
+- **WHEN** a rule has an unknown type, a `MATCH` that is not last or is nested, a missing value where required (or a value where not allowed), `no-resolve` on an unsupported type, an out-of-range provider reference, a top-level rule without a target, or a nested rule that carries a target
+- **THEN** the response is `400` reporting that specific rule error
+
+#### Scenario: Logical-rule arity
+
+- **WHEN** a `NOT` rule does not have exactly one child, or an `AND`/`OR` rule has fewer than two children
+- **THEN** the response is `400` reporting the arity error
+
+#### Scenario: Rule-provider validation
+
+- **WHEN** a provider has an empty name or URL, an unknown behavior, or an unknown format
+- **THEN** the response is `400` reporting that specific provider error
+
+#### Scenario: Duplicate provider name
+
+- **WHEN** two providers in the config share a name
+- **THEN** the save fails `400` reporting the provider name is taken (`entity.ErrRuleProviderNameTaken`, from the database constraint)
+
+#### Scenario: Base YAML guard
+
+- **WHEN** the base YAML does not parse, or contains a generated key (`proxies`, `proxy-groups`, `rules`, `rule-providers`, `sub-rules`)
+- **THEN** the response is `400` reporting the invalid YAML or the generated key
+
+#### Scenario: Profile validation
+
+- **WHEN** the profile title or filename is empty, the filename contains `/`, `\`, or control characters, or the update interval is not a positive number
+- **THEN** the response is `400` reporting that specific profile error
+
+### Requirement: List custom configs
+
+`GET /admin/api/config/mihomo/customs` SHALL return the set of users that have a custom config
+alongside the full user list, so the admin can scope edits.
+
+#### Scenario: Customs and users returned
+
+- **WHEN** `GET /admin/api/config/mihomo/customs` is called
+- **THEN** the response is `200` with `{ customs, users }`, where `customs` is a subset of `users`
+
+### Requirement: Create custom config by cloning the base
+
+`POST /admin/api/config/mihomo/custom/create` SHALL create a user's custom config as an
+independent clone of the base, refusing if one already exists.
+
+#### Scenario: Clone created
+
+- **WHEN** a `userId` with no existing custom config is posted
+- **THEN** the response is `200` and a custom config is created from a snapshot of the base
+
+#### Scenario: Custom already exists
+
+- **WHEN** a `userId` that already has a custom config is posted
+- **THEN** the response is `400` reporting the custom already exists (`entity.ErrUserConfigExists`)
+
+### Requirement: Delete custom config
+
+`POST /admin/api/config/mihomo/custom/delete` SHALL delete a user's custom config (reverting them
+to the base), refusing if none exists.
+
+#### Scenario: Custom deleted
+
+- **WHEN** a `userId` that has a custom config is posted
+- **THEN** the response is `200` and the custom config is removed
+
+#### Scenario: No custom to delete
+
+- **WHEN** a `userId` with no custom config is posted
+- **THEN** the response is `400` reporting the user has no custom config (`entity.ErrUserConfigNotFound`)
+
+### Requirement: Probe a rule provider
+
+`POST /admin/api/config/mihomo/provider/check` SHALL fetch a provider URL read-only and report a
+typed outcome without persisting anything.
+
+#### Scenario: Reachable and matching
+
+- **WHEN** the URL returns `200` with content matching the declared format
+- **THEN** the response is `200` describing the format and size
+
+#### Scenario: Unreachable, HTTP error, empty, or format mismatch
+
+- **WHEN** the URL cannot be reached, returns a non-`200` status, returns an empty body, or returns content not matching the declared format
+- **THEN** the response is `400` reporting that specific outcome
diff --git a/openspec/specs/mihomo-rendering/spec.md b/openspec/specs/mihomo-rendering/spec.md
new file mode 100644
index 0000000..f7d40a8
--- /dev/null
+++ b/openspec/specs/mihomo-rendering/spec.md
@@ -0,0 +1,64 @@
+# Mihomo Rendering Spec
+
+## Purpose
+
+How a stored mihomo config plus one subscriber's live proxies become the YAML the client
+downloads. A per-subscriber resolver turns each typed `PolicyRef` into a concrete proxy name:
+built-in policies map to their constant, inbound references map to the subscriber's matching
+proxy, group references map to the group name. References the subscriber cannot satisfy are
+dropped silently, and an empty group degrades to `DIRECT` on the client. The base YAML preamble
+is preserved and the generated sections (`proxies`, `proxy-groups`, `rules`, `rule-providers`,
+`sub-rules`) are appended.
+
+## Requirements
+
+### Requirement: Resolve policy references per subscriber
+
+Rendering SHALL resolve each `PolicyRef` against the subscriber's own proxies and the config's
+groups/providers: built-in kinds to their uppercase constant, an inbound reference to the
+subscriber's proxy for that inbound, a group reference to the group name.
+
+#### Scenario: Built-in policy
+
+- **WHEN** a reference is a built-in policy (e.g. `direct`, `reject`)
+- **THEN** it renders to the corresponding policy name, which is always available
+
+#### Scenario: Inbound available to the subscriber
+
+- **WHEN** a reference points to an inbound the subscriber has a proxy for
+- **THEN** it renders to that proxy's name
+
+### Requirement: Drop unavailable references
+
+Rendering SHALL omit a member or rule whose inbound, group, or provider reference cannot be
+resolved for the subscriber, rather than emitting a dangling name.
+
+#### Scenario: Inbound not available
+
+- **WHEN** a member or rule references an inbound the subscriber has no proxy for
+- **THEN** that member/rule is omitted from the rendered YAML
+
+#### Scenario: Subscriber with no proxies
+
+- **WHEN** the subscriber has no proxies at all
+- **THEN** every inbound reference drops, leaving groups empty
+
+### Requirement: Empty group degrades to DIRECT
+
+Rendering SHALL emit a proxy group with no remaining members as an empty group, which the mihomo
+client treats as `DIRECT`.
+
+#### Scenario: All members dropped
+
+- **WHEN** every member of a group resolves to an unavailable inbound
+- **THEN** the group is rendered with no members (the client falls back to `DIRECT`)
+
+### Requirement: Preserve base YAML and append generated sections
+
+Rendering SHALL keep the operator's base YAML preamble and append the generated `proxies`,
+`proxy-groups`, `rules`, `rule-providers`, and `sub-rules` sections.
+
+#### Scenario: Base preserved, generated appended
+
+- **WHEN** a config with a base YAML preamble is rendered
+- **THEN** the output contains the base YAML plus the generated sections, with no generated key duplicated in the base
diff --git a/openspec/specs/nodes/spec.md b/openspec/specs/nodes/spec.md
new file mode 100644
index 0000000..5b0f828
--- /dev/null
+++ b/openspec/specs/nodes/spec.md
@@ -0,0 +1,76 @@
+# Nodes Spec
+
+## Purpose
+
+The registry of VPN nodes and their inbounds. A node carries its public VPN host and the
+coordinates of its 3x-ui panel; each node owns one or more inbounds identified by port. Node and
+inbound shapes are validated in the service with sentinel errors mapped to typed `4xx`;
+uniqueness and referential integrity are enforced by the database. Inbounds are referenced by
+numeric id everywhere except when matching the external 3x-ui inbound by port.
+
+## Requirements
+
+### Requirement: List nodes
+
+`GET /admin/api/nodes` SHALL return all nodes with their panel coordinates and inbounds.
+
+#### Scenario: Nodes returned with inbounds
+
+- **WHEN** `GET /admin/api/nodes` is called
+- **THEN** the response is `200` with `{ nodes }`, each node carrying `id`, `name`, `vpnHost`, `panelBaseURL`, `panelBasePath`, and its `inbounds` (each `id`, `name`, `port`)
+
+### Requirement: Save node with field validation
+
+`POST /admin/api/nodes/save` SHALL create a node when no id is given and update it otherwise,
+validating every field in the service and mapping each failure to a `400`.
+
+#### Scenario: Create vs update
+
+- **WHEN** the request has no id (or id `0`)
+- **THEN** a new node is created; **WHEN** the id is positive, the existing node is updated
+- **AND** on success the response is `200` with a confirmation message
+
+#### Scenario: Inputs trimmed and blank inbound rows skipped
+
+- **WHEN** a save includes surrounding whitespace and inbound rows with port `0`
+- **THEN** string fields are trimmed and the blank inbound rows are ignored
+
+#### Scenario: Invalid node fields
+
+- **WHEN** the node name, VPN host, panel base URL, or panel base path is malformed
+- **THEN** the response is `400` reporting the specific field (node name / host / panel URL / base path)
+
+#### Scenario: Inbound list and inbound fields
+
+- **WHEN** the node has no inbounds, or an inbound has an invalid name or a port outside 1–65535
+- **THEN** the response is `400` reporting the specific inbound validation error
+
+#### Scenario: Per-node inbound uniqueness
+
+- **WHEN** two inbounds on the node share a name or a port
+- **THEN** the response is `400` reporting the duplicate inbound name or port
+
+#### Scenario: Node name already taken
+
+- **WHEN** the node name collides with another node
+- **THEN** the response is `409` reporting the name is taken (`entity.ErrNodeNameTaken`)
+
+### Requirement: Delete node guarded by references
+
+`POST /admin/api/nodes/delete` SHALL delete a node and MUST refuse when any inbound is still
+referenced by a user or a routing rule.
+
+#### Scenario: Node not found
+
+- **WHEN** the id does not match any node
+- **THEN** the response is `400` reporting the node was not found (`entity.ErrNodeNotFound`)
+
+#### Scenario: Inbound still referenced
+
+- **WHEN** an inbound of the node is still referenced by a user connection or a rule/member (FK RESTRICT)
+- **THEN** the response is `400` reporting the node is in use (`entity.ErrInboundReferenced`) and nothing is deleted
+
+#### Scenario: Successful deletion
+
+- **WHEN** the node exists and none of its inbounds are referenced
+- **THEN** the response is `200` with a confirmation message and the node is removed
diff --git a/openspec/specs/platform/spec.md b/openspec/specs/platform/spec.md
new file mode 100644
index 0000000..4e0c4cd
--- /dev/null
+++ b/openspec/specs/platform/spec.md
@@ -0,0 +1,34 @@
+# Platform Spec
+
+## Purpose
+
+The non-feature HTTP surface that supports operations and the admin UI: a liveness probe and the
+static asset handler. The ogen server is the only typed `http.Handler`; the static route is the
+single exception, mounted alongside it on the stdlib mux. Static assets are served from the
+embedded copy by default, or live from disk for local development.
+
+## Requirements
+
+### Requirement: Liveness probe
+
+`GET /healthz` SHALL return `200` with a plain-text body and require no authentication.
+
+#### Scenario: Health check
+
+- **WHEN** `GET /healthz` is called
+- **THEN** the response is `200` with a plain-text `ok` body
+
+### Requirement: Static asset serving
+
+`GET /admin/static/*` SHALL serve the admin UI assets, from the embedded copy by default and from
+disk when a static directory override is configured.
+
+#### Scenario: Default embedded assets
+
+- **WHEN** no static-directory override is set
+- **THEN** assets are served from the embedded copy (a self-contained image)
+
+#### Scenario: Live-from-disk override
+
+- **WHEN** a static-directory override is configured
+- **THEN** assets are served live from that directory, so CSS/JS edits show on reload without rebuilding
diff --git a/openspec/specs/rule-provider-mirror/spec.md b/openspec/specs/rule-provider-mirror/spec.md
new file mode 100644
index 0000000..32935af
--- /dev/null
+++ b/openspec/specs/rule-provider-mirror/spec.md
@@ -0,0 +1,49 @@
+# Rule-Provider Mirror Spec
+
+## Purpose
+
+subgen can mirror upstream rule-provider files so clients fetch them from subgen instead of the
+origin. A background service fetches each mirrored provider referenced by any config (base or
+custom), refreshes it on an interval, and keeps the last good copy when a refresh fails. The
+public endpoint `GET /rules/{file}` serves the cached bytes with content-sniffing disabled.
+
+## Requirements
+
+### Requirement: Serve mirrored files
+
+`GET /rules/{file}` SHALL return a mirrored file's bytes with `X-Content-Type-Options: nosniff`,
+and `404` when the file is not in the mirror.
+
+#### Scenario: File present
+
+- **WHEN** `GET /rules/{file}` requests a file held in the mirror
+- **THEN** the response is `200` with the file bytes and `X-Content-Type-Options: nosniff`
+
+#### Scenario: File absent
+
+- **WHEN** the requested file is not in the mirror
+- **THEN** the response is `404`
+
+### Requirement: Background refresh keeps the last good copy
+
+The mirror SHALL refresh each mirrored provider on its interval and MUST keep the last good copy
+when a refresh fails or returns empty, so a transient upstream outage never empties the cache.
+
+#### Scenario: Successful refresh
+
+- **WHEN** a refresh fetches new content successfully
+- **THEN** the cached copy is replaced with the new bytes
+
+#### Scenario: Failed or empty refresh
+
+- **WHEN** a refresh errors or returns an empty body
+- **THEN** the previously cached copy is kept unchanged
+
+### Requirement: Mirror set covers all configs
+
+The mirror SHALL include the mirrored providers referenced by any config, base or custom.
+
+#### Scenario: Provider from a custom config
+
+- **WHEN** a custom config references a mirrored provider
+- **THEN** that provider is included in the mirror set
diff --git a/openspec/specs/subscription-delivery/spec.md b/openspec/specs/subscription-delivery/spec.md
new file mode 100644
index 0000000..bfdce3c
--- /dev/null
+++ b/openspec/specs/subscription-delivery/spec.md
@@ -0,0 +1,74 @@
+# Subscription Delivery Spec
+
+## Purpose
+
+The public subscription endpoint clients poll: `GET /sub/{kind}/{token}`. The `kind` selects an
+engine renderer from a registry; the `token` is an HMAC over the user's `subId`. The handler
+resolves the token to a service-owned user, picks that user's custom config for the kind (or the
+base), renders it for the user's live proxies, and returns the YAML with the metadata headers
+mihomo/Clash clients consume. The path is engine-generic: adding an engine is one renderer
+registration, no handler change.
+
+## Requirements
+
+### Requirement: Engine-generic subscription route
+
+`GET /sub/{kind}/{token}` SHALL validate `kind` against the renderer registry and render through
+the matching engine, returning `404` for an unknown kind.
+
+#### Scenario: Known kind
+
+- **WHEN** `kind` matches a registered engine renderer
+- **THEN** the request is rendered by that engine
+
+#### Scenario: Unknown kind
+
+- **WHEN** `kind` has no registered renderer
+- **THEN** the response is `404`
+
+### Requirement: Token resolves to a service-owned user
+
+The handler SHALL accept the token only if it HMAC-matches the `subId` of a user owned by the
+service, returning `404` otherwise.
+
+#### Scenario: Valid token
+
+- **WHEN** the token matches a service-owned user's `subId` under the configured secret
+- **THEN** that user is selected for rendering
+
+#### Scenario: Unmatched token
+
+- **WHEN** the token matches no service-owned user
+- **THEN** the response is `404`
+
+#### Scenario: Client provisioned directly on a panel
+
+- **WHEN** a token would correspond to a client created directly on a panel (not via the service)
+- **THEN** it is not served (only service-owned users are matched)
+
+### Requirement: Custom-else-base config selection
+
+The handler SHALL render the user's custom config for the requested kind when it exists, and
+otherwise the base config.
+
+#### Scenario: User has a custom
+
+- **WHEN** the resolved user has a custom config for the kind
+- **THEN** that custom config is rendered
+
+#### Scenario: User has no custom
+
+- **WHEN** the resolved user has no custom config for the kind
+- **THEN** the base config is rendered
+
+### Requirement: Subscription metadata headers
+
+A successful subscription response SHALL carry the client-facing metadata headers:
+profile update interval, base64 profile title, content-disposition filename, and the user-info
+traffic line.
+
+#### Scenario: Headers present on success
+
+- **WHEN** a subscription is served successfully
+- **THEN** the response includes `Profile-Update-Interval` (hours), a base64 `Profile-Title`, a `Content-Disposition` filename, and a `Subscription-Userinfo` line
+- **AND** the body is the rendered engine config
diff --git a/openspec/specs/user-provisioning/spec.md b/openspec/specs/user-provisioning/spec.md
new file mode 100644
index 0000000..5af4522
--- /dev/null
+++ b/openspec/specs/user-provisioning/spec.md
@@ -0,0 +1,75 @@
+# User Provisioning Spec
+
+## Purpose
+
+How a subgen user maps onto 3x-ui panel clients across the fleet. The invariant: a user is
+**one client per panel** — a single VLESS `uuid` whose `email` is the user's nickname and whose
+`subId` is shared across panels — bound to all of the user's inbounds on that panel with a single
+`add` call. Edits re-bind the same client (keeping the uuid); deletes and recreates are
+best-effort across panels. These rules exist because of hard-won 3x-ui quirks documented in
+`AGENTS.md`.
+
+## Requirements
+
+### Requirement: One client per panel, multi-inbound bind
+
+Provisioning SHALL create exactly one 3x-ui client per panel — one `uuid`, `email` = nickname,
+shared `subId` — and MUST bind it to all of the user's inbounds on that panel in a single `add`
+call.
+
+#### Scenario: User spans multiple inbounds on a panel
+
+- **WHEN** a user selects several inbounds that live on the same panel
+- **THEN** one client is added on that panel with one uuid bound to all those inbounds in a single call
+- **AND** the same `subId` is used for the user on every panel
+
+#### Scenario: Edit keeps the uuid
+
+- **WHEN** a user's inbound set changes on a panel it already occupies
+- **THEN** the existing client is re-bound and its uuid is preserved
+
+### Requirement: Email-collision guard before binding
+
+Before binding a user onto a panel it does not yet occupy, provisioning SHALL verify the
+nickname (email) is free on that panel and fail closed if the panel cannot be listed.
+
+#### Scenario: Email already used on a new panel
+
+- **WHEN** a panel being added already has a client whose email equals the user's nickname
+- **THEN** provisioning aborts with `entity.PanelClientExistsError` naming that node, making no changes
+
+#### Scenario: Panel unreachable during the guard
+
+- **WHEN** a panel cannot be listed during the collision check
+- **THEN** provisioning fails closed (returns the error) rather than risk provisioning blindly
+
+#### Scenario: Already-owned panels are exempt
+
+- **WHEN** a user is edited on a panel it already occupies
+- **THEN** the collision guard does not run for that panel (the client there is already the user's)
+
+### Requirement: Best-effort delete across panels
+
+Deleting a user SHALL attempt to remove its client from each panel by email and MUST treat a
+client that is already absent as success.
+
+#### Scenario: Client missing on a panel
+
+- **WHEN** a delete runs and the client is not found on a panel
+- **THEN** that panel is treated as already-clean (idempotent) and deletion continues
+
+#### Scenario: Panel unreachable during delete
+
+- **WHEN** a panel is unreachable during delete
+- **THEN** deletion proceeds on the other panels and the user row is still removed
+
+### Requirement: Recreate re-binds from stored state
+
+Recreating a user SHALL force a full re-bind of its panel clients from the stored connection
+set, preserving uuids where the user already owns a client.
+
+#### Scenario: Repair drift
+
+- **WHEN** a recreate runs for a user
+- **THEN** each panel in the stored connection set is re-bound for the user
+- **AND** uuids are preserved on panels the user already occupies