feat: suivi de la progression de lecture par livre

- API : nouvelle table book_reading_progress (migration 0016) et module
  reading_progress.rs avec GET/PATCH /books/:id/progress (token read)
- API : GET /books/:id enrichi avec reading_status, reading_current_page,
  reading_last_read_at via LEFT JOIN
- Backoffice : badge de statut (Non lu / En cours · p.N / Lu) sur la page
  de détail et overlay sur les BookCards
- OpenSpec : change reading-progress avec proposal/design/specs/tasks

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.claude/commands/opsx/apply.md

@@ -0,0 +1,152 @@
+---
+name: "OPSX: Apply"
+description: Implement tasks from an OpenSpec change (Experimental)
+category: Workflow
+tags: [workflow, artifacts, experimental]
+---
+
+Implement tasks from an OpenSpec change.
+
+**Input**: Optionally specify a change name (e.g., `/opsx:apply add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **Select the change**
+
+   If a name is provided, use it. Otherwise:
+   - Infer from conversation context if the user mentioned a change
+   - Auto-select if only one active change exists
+   - If ambiguous, run `openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select
+
+   Always announce: "Using change: <name>" and how to override (e.g., `/opsx:apply <other>`).
+
+2. **Check status to understand the schema**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used (e.g., "spec-driven")
+   - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
+
+3. **Get apply instructions**
+
+   ```bash
+   openspec instructions apply --change "<name>" --json
+   ```
+
+   This returns:
+   - Context 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 the files listed in `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

.claude/commands/opsx/archive.md

@@ -0,0 +1,157 @@
+---
+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.
+
+**Input**: Optionally specify a change name after `/opsx:archive` (e.g., `/opsx:archive add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+
+   Show only active changes (not already archived).
+   Include the schema used for each change if available.
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Check artifact completion status**
+
+   Run `openspec status --change "<name>" --json` to check artifact completion.
+
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used
+   - `artifacts`: List of artifacts with their status (`done` or other)
+
+   **If any artifacts are not `done`:**
+   - Display warning listing incomplete artifacts
+   - Prompt user for confirmation to continue
+   - Proceed if user confirms
+
+3. **Check task completion status**
+
+   Read the tasks file (typically `tasks.md`) to check for incomplete tasks.
+
+   Count tasks marked with `- [ ]` (incomplete) vs `- [x]` (complete).
+
+   **If incomplete tasks found:**
+   - Display warning showing count of incomplete tasks
+   - Prompt user for confirmation to continue
+   - Proceed if user confirms
+
+   **If no tasks file exists:** Proceed without task-related warning.
+
+4. **Assess delta spec sync state**
+
+   Check for delta specs at `openspec/changes/<name>/specs/`. If none exist, proceed without sync prompt.
+
+   **If delta specs exist:**
+   - Compare each delta spec with its corresponding main spec at `openspec/specs/<capability>/spec.md`
+   - Determine what changes would be applied (adds, modifications, removals, renames)
+   - Show a combined summary before prompting
+
+   **Prompt options:**
+   - If changes needed: "Sync now (recommended)", "Archive without syncing"
+   - If already synced: "Archive now", "Sync anyway", "Cancel"
+
+   If user chooses sync, use Task tool (subagent_type: "general-purpose", prompt: "Use Skill tool to invoke openspec-sync-specs for change '<name>'. Delta spec analysis: <include the analyzed delta spec summary>"). Proceed to archive regardless of choice.
+
+5. **Perform the archive**
+
+   Create the archive directory if it doesn't exist:
+   ```bash
+   mkdir -p openspec/changes/archive
+   ```
+
+   Generate target name using current date: `YYYY-MM-DD-<change-name>`
+
+   **Check if target already exists:**
+   - If yes: Fail with error, suggest renaming existing archive or using different date
+   - If no: Move the change directory to archive
+
+   ```bash
+   mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
+   ```
+
+6. **Display summary**
+
+   Show archive completion summary including:
+   - Change name
+   - Schema that was used
+   - Archive location
+   - Spec sync status (synced / sync skipped / no delta specs)
+   - Note about any warnings (incomplete artifacts/tasks)
+
+**Output On Success**
+
+```
+## Archive Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** ✓ Synced to main specs
+
+All artifacts complete. All tasks complete.
+```
+
+**Output On Success (No Delta Specs)**
+
+```
+## Archive Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** No delta specs
+
+All artifacts complete. All tasks complete.
+```
+
+**Output On Success With Warnings**
+
+```
+## Archive Complete (with warnings)
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** Sync skipped (user chose to skip)
+
+**Warnings:**
+- Archived with 2 incomplete artifacts
+- Archived with 3 incomplete tasks
+- Delta spec sync was skipped (user chose to skip)
+
+Review the archive if this was not intentional.
+```
+
+**Output On Error (Archive Exists)**
+
+```
+## Archive Failed
+
+**Change:** <change-name>
+**Target:** openspec/changes/archive/YYYY-MM-DD-<name>/
+
+Target archive directory already exists.
+
+**Options:**
+1. Rename the existing archive
+2. Delete the existing archive if it's a duplicate
+3. Wait until a different date to archive
+```
+
+**Guardrails**
+- Always prompt for change selection if not provided
+- Use artifact graph (openspec status --json) for completion checking
+- Don't block archive on warnings - just inform and confirm
+- Preserve .openspec.yaml when moving to archive (it moves with the directory)
+- Show clear summary of what happened
+- If sync is requested, use the Skill tool to invoke `openspec-sync-specs` (agent-driven)
+- If delta specs exist, always run the sync assessment and show the combined summary before prompting

.claude/commands/opsx/explore.md

@@ -0,0 +1,173 @@
+---
+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.
+
+**Input**: The argument after `/opsx:explore` is whatever the user wants to think about. Could be:
+- A vague idea: "real-time collaboration"
+- A specific problem: "the auth system is getting unwieldy"
+- A change name: "add-dark-mode" (to explore in context of that change)
+- A comparison: "postgres vs sqlite for this"
+- Nothing (just enter explore mode)
+
+---
+
+## The Stance
+
+- **Curious, not prescriptive** - Ask questions that emerge naturally, don't follow a script
+- **Open threads, not interrogations** - Surface multiple interesting directions and let the user follow what resonates. Don't funnel them through a single path of questions.
+- **Visual** - Use ASCII diagrams liberally when they'd help clarify thinking
+- **Adaptive** - Follow interesting threads, pivot when new information emerges
+- **Patient** - Don't rush to conclusions, let the shape of the problem emerge
+- **Grounded** - Explore the actual codebase when relevant, don't just theorize
+
+---
+
+## What You Might Do
+
+Depending on what the user brings, you might:
+
+**Explore the problem space**
+- Ask clarifying questions that emerge from what they said
+- Challenge assumptions
+- Reframe the problem
+- Find analogies
+
+**Investigate the codebase**
+- Map existing architecture relevant to the discussion
+- Find integration points
+- Identify patterns already in use
+- Surface hidden complexity
+
+**Compare options**
+- Brainstorm multiple approaches
+- Build comparison tables
+- Sketch tradeoffs
+- Recommend a path (if asked)
+
+**Visualize**
+```
+┌─────────────────────────────────────────┐
+│     Use ASCII diagrams liberally        │
+├─────────────────────────────────────────┤
+│                                         │
+│   ┌────────┐         ┌────────┐        │
+│   │ State  │────────▶│ State  │        │
+│   │   A    │         │   B    │        │
+│   └────────┘         └────────┘        │
+│                                         │
+│   System diagrams, state machines,      │
+│   data flows, architecture sketches,    │
+│   dependency graphs, comparison tables  │
+│                                         │
+└─────────────────────────────────────────┘
+```
+
+**Surface risks and unknowns**
+- Identify what could go wrong
+- Find gaps in understanding
+- Suggest spikes or investigations
+
+---
+
+## OpenSpec Awareness
+
+You have full context of the OpenSpec system. Use it naturally, don't force it.
+
+### Check for context
+
+At the start, quickly check what exists:
+```bash
+openspec list --json
+```
+
+This tells you:
+- If there are active changes
+- Their names, schemas, and status
+- What the user might be working on
+
+If the user mentioned a specific change name, read its artifacts for context.
+
+### When no change exists
+
+Think freely. When insights crystallize, you might offer:
+
+- "This feels solid enough to start a change. Want me to create a proposal?"
+- Or keep exploring - no pressure to formalize
+
+### When a change exists
+
+If the user mentions a change or you detect one is relevant:
+
+1. **Read existing artifacts for context**
+   - `openspec/changes/<name>/proposal.md`
+   - `openspec/changes/<name>/design.md`
+   - `openspec/changes/<name>/tasks.md`
+   - etc.
+
+2. **Reference them naturally in conversation**
+   - "Your design mentions using Redis, but we just realized SQLite fits better..."
+   - "The proposal scopes this to premium users, but we're now thinking everyone..."
+
+3. **Offer to capture when decisions are made**
+
+   | Insight Type | Where to Capture |
+   |--------------|------------------|
+   | New requirement discovered | `specs/<capability>/spec.md` |
+   | Requirement changed | `specs/<capability>/spec.md` |
+   | Design decision made | `design.md` |
+   | Scope changed | `proposal.md` |
+   | New work identified | `tasks.md` |
+   | Assumption invalidated | Relevant artifact |
+
+   Example offers:
+   - "That's a design decision. Capture it in design.md?"
+   - "This is a new requirement. Add it to specs?"
+   - "This changes scope. Update the proposal?"
+
+4. **The user decides** - Offer and move on. Don't pressure. Don't auto-capture.
+
+---
+
+## What You Don't Have To Do
+
+- Follow a script
+- Ask the same questions every time
+- Produce a specific artifact
+- Reach a conclusion
+- Stay on topic if a tangent is valuable
+- Be brief (this is thinking time)
+
+---
+
+## Ending Discovery
+
+There's no required ending. Discovery might:
+
+- **Flow into a proposal**: "Ready to start? I can create a change proposal."
+- **Result in artifact updates**: "Updated design.md with these decisions"
+- **Just provide clarity**: User has what they need, moves on
+- **Continue later**: "We can pick this up anytime"
+
+When things crystallize, you might offer a summary - but it's optional. Sometimes the thinking IS the value.
+
+---
+
+## Guardrails
+
+- **Don't implement** - Never write code or implement features. Creating OpenSpec artifacts is fine, writing application code is not.
+- **Don't fake understanding** - If something is unclear, dig deeper
+- **Don't rush** - Discovery is thinking time, not task time
+- **Don't force structure** - Let patterns emerge naturally
+- **Don't auto-capture** - Offer to save insights, don't just do it
+- **Do visualize** - A good diagram is worth many paragraphs
+- **Do explore the codebase** - Ground discussions in reality
+- **Do question assumptions** - Including the user's and your own

.claude/commands/opsx/propose.md

@@ -0,0 +1,106 @@
+---
+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
+
+---
+
+**Input**: The argument after `/opsx:propose` is the change name (kebab-case), OR a description of what the user wants to build.
+
+**Steps**
+
+1. **If no input provided, ask what they want to build**
+
+   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+   > "What change do you want to work on? Describe what you want to build or fix."
+
+   From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
+
+   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
+
+2. **Create the change directory**
+   ```bash
+   openspec new change "<name>"
+   ```
+   This creates a scaffolded change at `openspec/changes/<name>/` with `.openspec.yaml`.
+
+3. **Get the artifact build order**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to get:
+   - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
+   - `artifacts`: list of all artifacts with their status and dependencies
+
+4. **Create artifacts in sequence until apply-ready**
+
+   Use the **TodoWrite tool** to track progress through the artifacts.
+
+   Loop through artifacts in dependency order (artifacts with no pending dependencies first):
+
+   a. **For each artifact that is `ready` (dependencies satisfied)**:
+      - Get instructions:
+        ```bash
+        openspec instructions <artifact-id> --change "<name>" --json
+        ```
+      - The instructions JSON includes:
+        - `context`: Project background (constraints for you - do NOT include in output)
+        - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
+        - `template`: The structure to use for your output file
+        - `instruction`: Schema-specific guidance for this artifact type
+        - `outputPath`: Where to write the artifact
+        - `dependencies`: Completed artifacts to read for context
+      - Read any completed dependency files for context
+      - Create the artifact file using `template` as the structure
+      - Apply `context` and `rules` as constraints - but do NOT copy them into the file
+      - Show brief progress: "Created <artifact-id>"
+
+   b. **Continue until all `applyRequires` artifacts are complete**
+      - After creating each artifact, re-run `openspec status --change "<name>" --json`
+      - Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array
+      - Stop when all `applyRequires` artifacts are done
+
+   c. **If an artifact requires user input** (unclear context):
+      - Use **AskUserQuestion tool** to clarify
+      - Then continue with creation
+
+5. **Show final status**
+   ```bash
+   openspec status --change "<name>"
+   ```
+
+**Output**
+
+After completing all artifacts, summarize:
+- Change name and location
+- List of artifacts created with brief descriptions
+- What's ready: "All artifacts created! Ready for implementation."
+- Prompt: "Run `/opsx:apply` to start implementing."
+
+**Artifact Creation Guidelines**
+
+- Follow the `instruction` field from `openspec instructions` for each artifact type
+- The schema defines what each artifact should contain - follow it
+- Read dependency artifacts for context before creating new ones
+- Use `template` as the structure for your output file - fill in its sections
+- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
+  - Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
+  - These guide what you write, but should never appear in the output
+
+**Guardrails**
+- Create ALL artifacts needed for implementation (as defined by schema's `apply.requires`)
+- Always read dependency artifacts before creating a new one
+- If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
+- If a change with that name already exists, ask if user wants to continue it or create a new one
+- Verify each artifact file exists after writing before proceeding to next

.claude/skills/openspec-apply-change/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: openspec-apply-change
+description: Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.2.0"
+---
+
+Implement tasks from an OpenSpec change.
+
+**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **Select the change**
+
+   If a name is provided, use it. Otherwise:
+   - Infer from conversation context if the user mentioned a change
+   - Auto-select if only one active change exists
+   - If ambiguous, run `openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select
+
+   Always announce: "Using change: <name>" and how to override (e.g., `/opsx:apply <other>`).
+
+2. **Check status to understand the schema**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used (e.g., "spec-driven")
+   - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
+
+3. **Get apply instructions**
+
+   ```bash
+   openspec instructions apply --change "<name>" --json
+   ```
+
+   This returns:
+   - Context 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 the files listed in `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

.claude/skills/openspec-archive-change/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: openspec-archive-change
+description: Archive a completed change in the experimental workflow. Use when the user wants to finalize and archive a change after implementation is complete.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.2.0"
+---
+
+Archive a completed change in the experimental workflow.
+
+**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+
+   Show only active changes (not already archived).
+   Include the schema used for each change if available.
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Check artifact completion status**
+
+   Run `openspec status --change "<name>" --json` to check artifact completion.
+
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used
+   - `artifacts`: List of artifacts with their status (`done` or other)
+
+   **If any artifacts are not `done`:**
+   - Display warning listing incomplete artifacts
+   - Use **AskUserQuestion tool** to confirm user wants to proceed
+   - Proceed if user confirms
+
+3. **Check task completion status**
+
+   Read the tasks file (typically `tasks.md`) to check for incomplete tasks.
+
+   Count tasks marked with `- [ ]` (incomplete) vs `- [x]` (complete).
+
+   **If incomplete tasks found:**
+   - Display warning showing count of incomplete tasks
+   - Use **AskUserQuestion tool** to confirm user wants to proceed
+   - Proceed if user confirms
+
+   **If no tasks file exists:** Proceed without task-related warning.
+
+4. **Assess delta spec sync state**
+
+   Check for delta specs at `openspec/changes/<name>/specs/`. If none exist, proceed without sync prompt.
+
+   **If delta specs exist:**
+   - Compare each delta spec with its corresponding main spec at `openspec/specs/<capability>/spec.md`
+   - Determine what changes would be applied (adds, modifications, removals, renames)
+   - Show a combined summary before prompting
+
+   **Prompt options:**
+   - If changes needed: "Sync now (recommended)", "Archive without syncing"
+   - If already synced: "Archive now", "Sync anyway", "Cancel"
+
+   If user chooses sync, use Task tool (subagent_type: "general-purpose", prompt: "Use Skill tool to invoke openspec-sync-specs for change '<name>'. Delta spec analysis: <include the analyzed delta spec summary>"). Proceed to archive regardless of choice.
+
+5. **Perform the archive**
+
+   Create the archive directory if it doesn't exist:
+   ```bash
+   mkdir -p openspec/changes/archive
+   ```
+
+   Generate target name using current date: `YYYY-MM-DD-<change-name>`
+
+   **Check if target already exists:**
+   - If yes: Fail with error, suggest renaming existing archive or using different date
+   - If no: Move the change directory to archive
+
+   ```bash
+   mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
+   ```
+
+6. **Display summary**
+
+   Show archive completion summary including:
+   - Change name
+   - Schema that was used
+   - Archive location
+   - Whether specs were synced (if applicable)
+   - Note about any warnings (incomplete artifacts/tasks)
+
+**Output On Success**
+
+```
+## Archive Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** ✓ Synced to main specs (or "No delta specs" or "Sync skipped")
+
+All artifacts complete. All tasks complete.
+```
+
+**Guardrails**
+- Always prompt for change selection if not provided
+- Use artifact graph (openspec status --json) for completion checking
+- Don't block archive on warnings - just inform and confirm
+- Preserve .openspec.yaml when moving to archive (it moves with the directory)
+- Show clear summary of what happened
+- If sync is requested, use openspec-sync-specs approach (agent-driven)
+- If delta specs exist, always run the sync assessment and show the combined summary before prompting

.claude/skills/openspec-explore/SKILL.md

@@ -0,0 +1,288 @@
+---
+name: openspec-explore
+description: Enter explore mode - a thinking partner for exploring ideas, investigating problems, and clarifying requirements. Use when the user wants to think through something before or during a change.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.2.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.
+
+---
+
+## The Stance
+
+- **Curious, not prescriptive** - Ask questions that emerge naturally, don't follow a script
+- **Open threads, not interrogations** - Surface multiple interesting directions and let the user follow what resonates. Don't funnel them through a single path of questions.
+- **Visual** - Use ASCII diagrams liberally when they'd help clarify thinking
+- **Adaptive** - Follow interesting threads, pivot when new information emerges
+- **Patient** - Don't rush to conclusions, let the shape of the problem emerge
+- **Grounded** - Explore the actual codebase when relevant, don't just theorize
+
+---
+
+## What You Might Do
+
+Depending on what the user brings, you might:
+
+**Explore the problem space**
+- Ask clarifying questions that emerge from what they said
+- Challenge assumptions
+- Reframe the problem
+- Find analogies
+
+**Investigate the codebase**
+- Map existing architecture relevant to the discussion
+- Find integration points
+- Identify patterns already in use
+- Surface hidden complexity
+
+**Compare options**
+- Brainstorm multiple approaches
+- Build comparison tables
+- Sketch tradeoffs
+- Recommend a path (if asked)
+
+**Visualize**
+```
+┌─────────────────────────────────────────┐
+│     Use ASCII diagrams liberally        │
+├─────────────────────────────────────────┤
+│                                         │
+│   ┌────────┐         ┌────────┐        │
+│   │ State  │────────▶│ State  │        │
+│   │   A    │         │   B    │        │
+│   └────────┘         └────────┘        │
+│                                         │
+│   System diagrams, state machines,      │
+│   data flows, architecture sketches,    │
+│   dependency graphs, comparison tables  │
+│                                         │
+└─────────────────────────────────────────┘
+```
+
+**Surface risks and unknowns**
+- Identify what could go wrong
+- Find gaps in understanding
+- Suggest spikes or investigations
+
+---
+
+## OpenSpec Awareness
+
+You have full context of the OpenSpec system. Use it naturally, don't force it.
+
+### Check for context
+
+At the start, quickly check what exists:
+```bash
+openspec list --json
+```
+
+This tells you:
+- If there are active changes
+- Their names, schemas, and status
+- What the user might be working on
+
+### When no change exists
+
+Think freely. When insights crystallize, you might offer:
+
+- "This feels solid enough to start a change. Want me to create a proposal?"
+- Or keep exploring - no pressure to formalize
+
+### When a change exists
+
+If the user mentions a change or you detect one is relevant:
+
+1. **Read existing artifacts for context**
+   - `openspec/changes/<name>/proposal.md`
+   - `openspec/changes/<name>/design.md`
+   - `openspec/changes/<name>/tasks.md`
+   - etc.
+
+2. **Reference them naturally in conversation**
+   - "Your design mentions using Redis, but we just realized SQLite fits better..."
+   - "The proposal scopes this to premium users, but we're now thinking everyone..."
+
+3. **Offer to capture when decisions are made**
+
+   | Insight Type | Where to Capture |
+   |--------------|------------------|
+   | New requirement discovered | `specs/<capability>/spec.md` |
+   | Requirement changed | `specs/<capability>/spec.md` |
+   | Design decision made | `design.md` |
+   | Scope changed | `proposal.md` |
+   | New work identified | `tasks.md` |
+   | Assumption invalidated | Relevant artifact |
+
+   Example offers:
+   - "That's a design decision. Capture it in design.md?"
+   - "This is a new requirement. Add it to specs?"
+   - "This changes scope. Update the proposal?"
+
+4. **The user decides** - Offer and move on. Don't pressure. Don't auto-capture.
+
+---
+
+## What You Don't Have To Do
+
+- Follow a script
+- Ask the same questions every time
+- Produce a specific artifact
+- Reach a conclusion
+- Stay on topic if a tangent is valuable
+- Be brief (this is thinking time)
+
+---
+
+## Handling Different Entry Points
+
+**User brings a vague idea:**
+```
+User: I'm thinking about adding real-time collaboration
+
+You: Real-time collab is a big space. Let me think about this...
+
+      COLLABORATION SPECTRUM
+      ════════════════════════════════════════════
+
+      Awareness          Coordination         Sync
+          │                   │                 │
+          ▼                   ▼                 ▼
+      ┌────────┐         ┌────────┐        ┌────────┐
+      │Presence│         │Cursors │        │  CRDT  │
+      │  "3    │         │ Multi  │        │Conflict│
+      │online" │         │ select │        │  free  │
+      └────────┘         └────────┘        └────────┘
+          │                   │                 │
+       trivial            moderate           complex
+
+      Where's your head at?
+```
+
+**User brings a specific problem:**
+```
+User: The auth system is a mess
+
+You: [reads codebase]
+
+     ┌─────────────────────────────────────────────┐
+     │              CURRENT AUTH FLOW              │
+     └─────────────────────────────────────────────┘
+                        │
+          ┌─────────────┼─────────────┐
+          ▼             ▼             ▼
+     ┌─────────┐  ┌─────────┐  ┌─────────┐
+     │ Google  │  │  GitHub │  │  Email  │
+     │  OAuth  │  │  OAuth  │  │  Magic  │
+     └────┬────┘  └────┬────┘  └────┬────┘
+          │             │             │
+          └─────────────┼─────────────┘
+                        ▼
+                  ┌───────────┐
+                  │  Session  │
+                  └─────┬─────┘
+                        │
+                        ▼
+                  ┌───────────┐
+                  │   Perms   │
+                  └───────────┘
+
+     I see three tangles. Which one's burning?
+```
+
+**User is stuck mid-implementation:**
+```
+User: /opsx:explore add-auth-system
+      The OAuth integration is more complex than expected
+
+You: [reads change artifacts]
+
+     You're on task 4: "Implement OAuth flow"
+
+     Let me trace what's involved...
+
+     [draws diagram, explores options, suggests paths]
+
+     Want to update the design to reflect this?
+     Or add a spike task to investigate?
+```
+
+**User wants to compare options:**
+```
+User: Should we use Postgres or SQLite?
+
+You: Generic answer is boring. What's the context?
+
+User: A CLI tool that tracks local dev environments
+
+You: That changes everything.
+
+     ┌─────────────────────────────────────────────────┐
+     │         CLI TOOL DATA STORAGE                  │
+     └─────────────────────────────────────────────────┘
+
+     Key constraints:
+     • No daemon running
+     • Must work offline
+     • Single user
+
+                  SQLite          Postgres
+     Deployment   embedded ✓      needs server ✗
+     Offline      yes ✓           no ✗
+     Single file  yes ✓           no ✗
+
+     SQLite. Not even close.
+
+     Unless... is there a sync component?
+```
+
+---
+
+## Ending Discovery
+
+There's no required ending. Discovery might:
+
+- **Flow into a proposal**: "Ready to start? I can create a change proposal."
+- **Result in artifact updates**: "Updated design.md with these decisions"
+- **Just provide clarity**: User has what they need, moves on
+- **Continue later**: "We can pick this up anytime"
+
+When it feels like things are crystallizing, you might summarize:
+
+```
+## What We Figured Out
+
+**The problem**: [crystallized understanding]
+
+**The approach**: [if one emerged]
+
+**Open questions**: [if any remain]
+
+**Next steps** (if ready):
+- Create a change proposal
+- Keep exploring: just keep talking
+```
+
+But this summary is optional. Sometimes the thinking IS the value.
+
+---
+
+## Guardrails
+
+- **Don't implement** - Never write code or implement features. Creating OpenSpec artifacts is fine, writing application code is not.
+- **Don't fake understanding** - If something is unclear, dig deeper
+- **Don't rush** - Discovery is thinking time, not task time
+- **Don't force structure** - Let patterns emerge naturally
+- **Don't auto-capture** - Offer to save insights, don't just do it
+- **Do visualize** - A good diagram is worth many paragraphs
+- **Do explore the codebase** - Ground discussions in reality
+- **Do question assumptions** - Including the user's and your own

.claude/skills/openspec-propose/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: openspec-propose
+description: Propose a new change with all artifacts generated in one step. Use when the user wants to quickly describe what they want to build and get a complete proposal with design, specs, and tasks ready for implementation.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.2.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
+
+---
+
+**Input**: The user's request should include a change name (kebab-case) OR a description of what they want to build.
+
+**Steps**
+
+1. **If no clear input provided, ask what they want to build**
+
+   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+   > "What change do you want to work on? Describe what you want to build or fix."
+
+   From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
+
+   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
+
+2. **Create the change directory**
+   ```bash
+   openspec new change "<name>"
+   ```
+   This creates a scaffolded change at `openspec/changes/<name>/` with `.openspec.yaml`.
+
+3. **Get the artifact build order**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to get:
+   - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
+   - `artifacts`: list of all artifacts with their status and dependencies
+
+4. **Create artifacts in sequence until apply-ready**
+
+   Use the **TodoWrite tool** to track progress through the artifacts.
+
+   Loop through artifacts in dependency order (artifacts with no pending dependencies first):
+
+   a. **For each artifact that is `ready` (dependencies satisfied)**:
+      - Get instructions:
+        ```bash
+        openspec instructions <artifact-id> --change "<name>" --json
+        ```
+      - The instructions JSON includes:
+        - `context`: Project background (constraints for you - do NOT include in output)
+        - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
+        - `template`: The structure to use for your output file
+        - `instruction`: Schema-specific guidance for this artifact type
+        - `outputPath`: Where to write the artifact
+        - `dependencies`: Completed artifacts to read for context
+      - Read any completed dependency files for context
+      - Create the artifact file using `template` as the structure
+      - Apply `context` and `rules` as constraints - but do NOT copy them into the file
+      - Show brief progress: "Created <artifact-id>"
+
+   b. **Continue until all `applyRequires` artifacts are complete**
+      - After creating each artifact, re-run `openspec status --change "<name>" --json`
+      - Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array
+      - Stop when all `applyRequires` artifacts are done
+
+   c. **If an artifact requires user input** (unclear context):
+      - Use **AskUserQuestion tool** to clarify
+      - Then continue with creation
+
+5. **Show final status**
+   ```bash
+   openspec status --change "<name>"
+   ```
+
+**Output**
+
+After completing all artifacts, summarize:
+- Change name and location
+- List of artifacts created with brief descriptions
+- What's ready: "All artifacts created! Ready for implementation."
+- Prompt: "Run `/opsx:apply` or ask me to implement to start working on the tasks."
+
+**Artifact Creation Guidelines**
+
+- Follow the `instruction` field from `openspec instructions` for each artifact type
+- The schema defines what each artifact should contain - follow it
+- Read dependency artifacts for context before creating new ones
+- Use `template` as the structure for your output file - fill in its sections
+- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
+  - Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
+  - These guide what you write, but should never appear in the output
+
+**Guardrails**
+- Create ALL artifacts needed for implementation (as defined by schema's `apply.requires`)
+- Always read dependency artifacts before creating a new one
+- If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
+- If a change with that name already exists, ask if user wants to continue it or create a new one
+- Verify each artifact file exists after writing before proceeding to next

.codex/skills/openspec-apply-change/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: openspec-apply-change
+description: Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.2.0"
+---
+
+Implement tasks from an OpenSpec change.
+
+**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **Select the change**
+
+   If a name is provided, use it. Otherwise:
+   - Infer from conversation context if the user mentioned a change
+   - Auto-select if only one active change exists
+   - If ambiguous, run `openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select
+
+   Always announce: "Using change: <name>" and how to override (e.g., `/opsx:apply <other>`).
+
+2. **Check status to understand the schema**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used (e.g., "spec-driven")
+   - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
+
+3. **Get apply instructions**
+
+   ```bash
+   openspec instructions apply --change "<name>" --json
+   ```
+
+   This returns:
+   - Context 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 the files listed in `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

.codex/skills/openspec-archive-change/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: openspec-archive-change
+description: Archive a completed change in the experimental workflow. Use when the user wants to finalize and archive a change after implementation is complete.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.2.0"
+---
+
+Archive a completed change in the experimental workflow.
+
+**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+
+   Show only active changes (not already archived).
+   Include the schema used for each change if available.
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Check artifact completion status**
+
+   Run `openspec status --change "<name>" --json` to check artifact completion.
+
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used
+   - `artifacts`: List of artifacts with their status (`done` or other)
+
+   **If any artifacts are not `done`:**
+   - Display warning listing incomplete artifacts
+   - Use **AskUserQuestion tool** to confirm user wants to proceed
+   - Proceed if user confirms
+
+3. **Check task completion status**
+
+   Read the tasks file (typically `tasks.md`) to check for incomplete tasks.
+
+   Count tasks marked with `- [ ]` (incomplete) vs `- [x]` (complete).
+
+   **If incomplete tasks found:**
+   - Display warning showing count of incomplete tasks
+   - Use **AskUserQuestion tool** to confirm user wants to proceed
+   - Proceed if user confirms
+
+   **If no tasks file exists:** Proceed without task-related warning.
+
+4. **Assess delta spec sync state**
+
+   Check for delta specs at `openspec/changes/<name>/specs/`. If none exist, proceed without sync prompt.
+
+   **If delta specs exist:**
+   - Compare each delta spec with its corresponding main spec at `openspec/specs/<capability>/spec.md`
+   - Determine what changes would be applied (adds, modifications, removals, renames)
+   - Show a combined summary before prompting
+
+   **Prompt options:**
+   - If changes needed: "Sync now (recommended)", "Archive without syncing"
+   - If already synced: "Archive now", "Sync anyway", "Cancel"
+
+   If user chooses sync, use Task tool (subagent_type: "general-purpose", prompt: "Use Skill tool to invoke openspec-sync-specs for change '<name>'. Delta spec analysis: <include the analyzed delta spec summary>"). Proceed to archive regardless of choice.
+
+5. **Perform the archive**
+
+   Create the archive directory if it doesn't exist:
+   ```bash
+   mkdir -p openspec/changes/archive
+   ```
+
+   Generate target name using current date: `YYYY-MM-DD-<change-name>`
+
+   **Check if target already exists:**
+   - If yes: Fail with error, suggest renaming existing archive or using different date
+   - If no: Move the change directory to archive
+
+   ```bash
+   mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
+   ```
+
+6. **Display summary**
+
+   Show archive completion summary including:
+   - Change name
+   - Schema that was used
+   - Archive location
+   - Whether specs were synced (if applicable)
+   - Note about any warnings (incomplete artifacts/tasks)
+
+**Output On Success**
+
+```
+## Archive Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** ✓ Synced to main specs (or "No delta specs" or "Sync skipped")
+
+All artifacts complete. All tasks complete.
+```
+
+**Guardrails**
+- Always prompt for change selection if not provided
+- Use artifact graph (openspec status --json) for completion checking
+- Don't block archive on warnings - just inform and confirm
+- Preserve .openspec.yaml when moving to archive (it moves with the directory)
+- Show clear summary of what happened
+- If sync is requested, use openspec-sync-specs approach (agent-driven)
+- If delta specs exist, always run the sync assessment and show the combined summary before prompting

.codex/skills/openspec-explore/SKILL.md

@@ -0,0 +1,288 @@
+---
+name: openspec-explore
+description: Enter explore mode - a thinking partner for exploring ideas, investigating problems, and clarifying requirements. Use when the user wants to think through something before or during a change.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.2.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.
+
+---
+
+## The Stance
+
+- **Curious, not prescriptive** - Ask questions that emerge naturally, don't follow a script
+- **Open threads, not interrogations** - Surface multiple interesting directions and let the user follow what resonates. Don't funnel them through a single path of questions.
+- **Visual** - Use ASCII diagrams liberally when they'd help clarify thinking
+- **Adaptive** - Follow interesting threads, pivot when new information emerges
+- **Patient** - Don't rush to conclusions, let the shape of the problem emerge
+- **Grounded** - Explore the actual codebase when relevant, don't just theorize
+
+---
+
+## What You Might Do
+
+Depending on what the user brings, you might:
+
+**Explore the problem space**
+- Ask clarifying questions that emerge from what they said
+- Challenge assumptions
+- Reframe the problem
+- Find analogies
+
+**Investigate the codebase**
+- Map existing architecture relevant to the discussion
+- Find integration points
+- Identify patterns already in use
+- Surface hidden complexity
+
+**Compare options**
+- Brainstorm multiple approaches
+- Build comparison tables
+- Sketch tradeoffs
+- Recommend a path (if asked)
+
+**Visualize**
+```
+┌─────────────────────────────────────────┐
+│     Use ASCII diagrams liberally        │
+├─────────────────────────────────────────┤
+│                                         │
+│   ┌────────┐         ┌────────┐        │
+│   │ State  │────────▶│ State  │        │
+│   │   A    │         │   B    │        │
+│   └────────┘         └────────┘        │
+│                                         │
+│   System diagrams, state machines,      │
+│   data flows, architecture sketches,    │
+│   dependency graphs, comparison tables  │
+│                                         │
+└─────────────────────────────────────────┘
+```
+
+**Surface risks and unknowns**
+- Identify what could go wrong
+- Find gaps in understanding
+- Suggest spikes or investigations
+
+---
+
+## OpenSpec Awareness
+
+You have full context of the OpenSpec system. Use it naturally, don't force it.
+
+### Check for context
+
+At the start, quickly check what exists:
+```bash
+openspec list --json
+```
+
+This tells you:
+- If there are active changes
+- Their names, schemas, and status
+- What the user might be working on
+
+### When no change exists
+
+Think freely. When insights crystallize, you might offer:
+
+- "This feels solid enough to start a change. Want me to create a proposal?"
+- Or keep exploring - no pressure to formalize
+
+### When a change exists
+
+If the user mentions a change or you detect one is relevant:
+
+1. **Read existing artifacts for context**
+   - `openspec/changes/<name>/proposal.md`
+   - `openspec/changes/<name>/design.md`
+   - `openspec/changes/<name>/tasks.md`
+   - etc.
+
+2. **Reference them naturally in conversation**
+   - "Your design mentions using Redis, but we just realized SQLite fits better..."
+   - "The proposal scopes this to premium users, but we're now thinking everyone..."
+
+3. **Offer to capture when decisions are made**
+
+   | Insight Type | Where to Capture |
+   |--------------|------------------|
+   | New requirement discovered | `specs/<capability>/spec.md` |
+   | Requirement changed | `specs/<capability>/spec.md` |
+   | Design decision made | `design.md` |
+   | Scope changed | `proposal.md` |
+   | New work identified | `tasks.md` |
+   | Assumption invalidated | Relevant artifact |
+
+   Example offers:
+   - "That's a design decision. Capture it in design.md?"
+   - "This is a new requirement. Add it to specs?"
+   - "This changes scope. Update the proposal?"
+
+4. **The user decides** - Offer and move on. Don't pressure. Don't auto-capture.
+
+---
+
+## What You Don't Have To Do
+
+- Follow a script
+- Ask the same questions every time
+- Produce a specific artifact
+- Reach a conclusion
+- Stay on topic if a tangent is valuable
+- Be brief (this is thinking time)
+
+---
+
+## Handling Different Entry Points
+
+**User brings a vague idea:**
+```
+User: I'm thinking about adding real-time collaboration
+
+You: Real-time collab is a big space. Let me think about this...
+
+      COLLABORATION SPECTRUM
+      ════════════════════════════════════════════
+
+      Awareness          Coordination         Sync
+          │                   │                 │
+          ▼                   ▼                 ▼
+      ┌────────┐         ┌────────┐        ┌────────┐
+      │Presence│         │Cursors │        │  CRDT  │
+      │  "3    │         │ Multi  │        │Conflict│
+      │online" │         │ select │        │  free  │
+      └────────┘         └────────┘        └────────┘
+          │                   │                 │
+       trivial            moderate           complex
+
+      Where's your head at?
+```
+
+**User brings a specific problem:**
+```
+User: The auth system is a mess
+
+You: [reads codebase]
+
+     ┌─────────────────────────────────────────────┐
+     │              CURRENT AUTH FLOW              │
+     └─────────────────────────────────────────────┘
+                        │
+          ┌─────────────┼─────────────┐
+          ▼             ▼             ▼
+     ┌─────────┐  ┌─────────┐  ┌─────────┐
+     │ Google  │  │  GitHub │  │  Email  │
+     │  OAuth  │  │  OAuth  │  │  Magic  │
+     └────┬────┘  └────┬────┘  └────┬────┘
+          │             │             │
+          └─────────────┼─────────────┘
+                        ▼
+                  ┌───────────┐
+                  │  Session  │
+                  └─────┬─────┘
+                        │
+                        ▼
+                  ┌───────────┐
+                  │   Perms   │
+                  └───────────┘
+
+     I see three tangles. Which one's burning?
+```
+
+**User is stuck mid-implementation:**
+```
+User: /opsx:explore add-auth-system
+      The OAuth integration is more complex than expected
+
+You: [reads change artifacts]
+
+     You're on task 4: "Implement OAuth flow"
+
+     Let me trace what's involved...
+
+     [draws diagram, explores options, suggests paths]
+
+     Want to update the design to reflect this?
+     Or add a spike task to investigate?
+```
+
+**User wants to compare options:**
+```
+User: Should we use Postgres or SQLite?
+
+You: Generic answer is boring. What's the context?
+
+User: A CLI tool that tracks local dev environments
+
+You: That changes everything.
+
+     ┌─────────────────────────────────────────────────┐
+     │         CLI TOOL DATA STORAGE                  │
+     └─────────────────────────────────────────────────┘
+
+     Key constraints:
+     • No daemon running
+     • Must work offline
+     • Single user
+
+                  SQLite          Postgres
+     Deployment   embedded ✓      needs server ✗
+     Offline      yes ✓           no ✗
+     Single file  yes ✓           no ✗
+
+     SQLite. Not even close.
+
+     Unless... is there a sync component?
+```
+
+---
+
+## Ending Discovery
+
+There's no required ending. Discovery might:
+
+- **Flow into a proposal**: "Ready to start? I can create a change proposal."
+- **Result in artifact updates**: "Updated design.md with these decisions"
+- **Just provide clarity**: User has what they need, moves on
+- **Continue later**: "We can pick this up anytime"
+
+When it feels like things are crystallizing, you might summarize:
+
+```
+## What We Figured Out
+
+**The problem**: [crystallized understanding]
+
+**The approach**: [if one emerged]
+
+**Open questions**: [if any remain]
+
+**Next steps** (if ready):
+- Create a change proposal
+- Keep exploring: just keep talking
+```
+
+But this summary is optional. Sometimes the thinking IS the value.
+
+---
+
+## Guardrails
+
+- **Don't implement** - Never write code or implement features. Creating OpenSpec artifacts is fine, writing application code is not.
+- **Don't fake understanding** - If something is unclear, dig deeper
+- **Don't rush** - Discovery is thinking time, not task time
+- **Don't force structure** - Let patterns emerge naturally
+- **Don't auto-capture** - Offer to save insights, don't just do it
+- **Do visualize** - A good diagram is worth many paragraphs
+- **Do explore the codebase** - Ground discussions in reality
+- **Do question assumptions** - Including the user's and your own

.codex/skills/openspec-propose/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: openspec-propose
+description: Propose a new change with all artifacts generated in one step. Use when the user wants to quickly describe what they want to build and get a complete proposal with design, specs, and tasks ready for implementation.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.2.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
+
+---
+
+**Input**: The user's request should include a change name (kebab-case) OR a description of what they want to build.
+
+**Steps**
+
+1. **If no clear input provided, ask what they want to build**
+
+   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+   > "What change do you want to work on? Describe what you want to build or fix."
+
+   From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
+
+   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
+
+2. **Create the change directory**
+   ```bash
+   openspec new change "<name>"
+   ```
+   This creates a scaffolded change at `openspec/changes/<name>/` with `.openspec.yaml`.
+
+3. **Get the artifact build order**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to get:
+   - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
+   - `artifacts`: list of all artifacts with their status and dependencies
+
+4. **Create artifacts in sequence until apply-ready**
+
+   Use the **TodoWrite tool** to track progress through the artifacts.
+
+   Loop through artifacts in dependency order (artifacts with no pending dependencies first):
+
+   a. **For each artifact that is `ready` (dependencies satisfied)**:
+      - Get instructions:
+        ```bash
+        openspec instructions <artifact-id> --change "<name>" --json
+        ```
+      - The instructions JSON includes:
+        - `context`: Project background (constraints for you - do NOT include in output)
+        - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
+        - `template`: The structure to use for your output file
+        - `instruction`: Schema-specific guidance for this artifact type
+        - `outputPath`: Where to write the artifact
+        - `dependencies`: Completed artifacts to read for context
+      - Read any completed dependency files for context
+      - Create the artifact file using `template` as the structure
+      - Apply `context` and `rules` as constraints - but do NOT copy them into the file
+      - Show brief progress: "Created <artifact-id>"
+
+   b. **Continue until all `applyRequires` artifacts are complete**
+      - After creating each artifact, re-run `openspec status --change "<name>" --json`
+      - Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array
+      - Stop when all `applyRequires` artifacts are done
+
+   c. **If an artifact requires user input** (unclear context):
+      - Use **AskUserQuestion tool** to clarify
+      - Then continue with creation
+
+5. **Show final status**
+   ```bash
+   openspec status --change "<name>"
+   ```
+
+**Output**
+
+After completing all artifacts, summarize:
+- Change name and location
+- List of artifacts created with brief descriptions
+- What's ready: "All artifacts created! Ready for implementation."
+- Prompt: "Run `/opsx:apply` or ask me to implement to start working on the tasks."
+
+**Artifact Creation Guidelines**
+
+- Follow the `instruction` field from `openspec instructions` for each artifact type
+- The schema defines what each artifact should contain - follow it
+- Read dependency artifacts for context before creating new ones
+- Use `template` as the structure for your output file - fill in its sections
+- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
+  - Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
+  - These guide what you write, but should never appear in the output
+
+**Guardrails**
+- Create ALL artifacts needed for implementation (as defined by schema's `apply.requires`)
+- Always read dependency artifacts before creating a new one
+- If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
+- If a change with that name already exists, ask if user wants to continue it or create a new one
+- Verify each artifact file exists after writing before proceeding to next

.cursor/commands/opsx-apply.md

@@ -0,0 +1,152 @@
+---
+name: /opsx-apply
+id: opsx-apply
+category: Workflow
+description: Implement tasks from an OpenSpec change (Experimental)
+---
+
+Implement tasks from an OpenSpec change.
+
+**Input**: Optionally specify a change name (e.g., `/opsx:apply add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **Select the change**
+
+   If a name is provided, use it. Otherwise:
+   - Infer from conversation context if the user mentioned a change
+   - Auto-select if only one active change exists
+   - If ambiguous, run `openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select
+
+   Always announce: "Using change: <name>" and how to override (e.g., `/opsx:apply <other>`).
+
+2. **Check status to understand the schema**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used (e.g., "spec-driven")
+   - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
+
+3. **Get apply instructions**
+
+   ```bash
+   openspec instructions apply --change "<name>" --json
+   ```
+
+   This returns:
+   - Context 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 the files listed in `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

.cursor/commands/opsx-archive.md

@@ -0,0 +1,157 @@
+---
+name: /opsx-archive
+id: opsx-archive
+category: Workflow
+description: Archive a completed change in the experimental workflow
+---
+
+Archive a completed change in the experimental workflow.
+
+**Input**: Optionally specify a change name after `/opsx:archive` (e.g., `/opsx:archive add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+
+   Show only active changes (not already archived).
+   Include the schema used for each change if available.
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Check artifact completion status**
+
+   Run `openspec status --change "<name>" --json` to check artifact completion.
+
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used
+   - `artifacts`: List of artifacts with their status (`done` or other)
+
+   **If any artifacts are not `done`:**
+   - Display warning listing incomplete artifacts
+   - Prompt user for confirmation to continue
+   - Proceed if user confirms
+
+3. **Check task completion status**
+
+   Read the tasks file (typically `tasks.md`) to check for incomplete tasks.
+
+   Count tasks marked with `- [ ]` (incomplete) vs `- [x]` (complete).
+
+   **If incomplete tasks found:**
+   - Display warning showing count of incomplete tasks
+   - Prompt user for confirmation to continue
+   - Proceed if user confirms
+
+   **If no tasks file exists:** Proceed without task-related warning.
+
+4. **Assess delta spec sync state**
+
+   Check for delta specs at `openspec/changes/<name>/specs/`. If none exist, proceed without sync prompt.
+
+   **If delta specs exist:**
+   - Compare each delta spec with its corresponding main spec at `openspec/specs/<capability>/spec.md`
+   - Determine what changes would be applied (adds, modifications, removals, renames)
+   - Show a combined summary before prompting
+
+   **Prompt options:**
+   - If changes needed: "Sync now (recommended)", "Archive without syncing"
+   - If already synced: "Archive now", "Sync anyway", "Cancel"
+
+   If user chooses sync, use Task tool (subagent_type: "general-purpose", prompt: "Use Skill tool to invoke openspec-sync-specs for change '<name>'. Delta spec analysis: <include the analyzed delta spec summary>"). Proceed to archive regardless of choice.
+
+5. **Perform the archive**
+
+   Create the archive directory if it doesn't exist:
+   ```bash
+   mkdir -p openspec/changes/archive
+   ```
+
+   Generate target name using current date: `YYYY-MM-DD-<change-name>`
+
+   **Check if target already exists:**
+   - If yes: Fail with error, suggest renaming existing archive or using different date
+   - If no: Move the change directory to archive
+
+   ```bash
+   mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
+   ```
+
+6. **Display summary**
+
+   Show archive completion summary including:
+   - Change name
+   - Schema that was used
+   - Archive location
+   - Spec sync status (synced / sync skipped / no delta specs)
+   - Note about any warnings (incomplete artifacts/tasks)
+
+**Output On Success**
+
+```
+## Archive Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** ✓ Synced to main specs
+
+All artifacts complete. All tasks complete.
+```
+
+**Output On Success (No Delta Specs)**
+
+```
+## Archive Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** No delta specs
+
+All artifacts complete. All tasks complete.
+```
+
+**Output On Success With Warnings**
+
+```
+## Archive Complete (with warnings)
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** Sync skipped (user chose to skip)
+
+**Warnings:**
+- Archived with 2 incomplete artifacts
+- Archived with 3 incomplete tasks
+- Delta spec sync was skipped (user chose to skip)
+
+Review the archive if this was not intentional.
+```
+
+**Output On Error (Archive Exists)**
+
+```
+## Archive Failed
+
+**Change:** <change-name>
+**Target:** openspec/changes/archive/YYYY-MM-DD-<name>/
+
+Target archive directory already exists.
+
+**Options:**
+1. Rename the existing archive
+2. Delete the existing archive if it's a duplicate
+3. Wait until a different date to archive
+```
+
+**Guardrails**
+- Always prompt for change selection if not provided
+- Use artifact graph (openspec status --json) for completion checking
+- Don't block archive on warnings - just inform and confirm
+- Preserve .openspec.yaml when moving to archive (it moves with the directory)
+- Show clear summary of what happened
+- If sync is requested, use the Skill tool to invoke `openspec-sync-specs` (agent-driven)
+- If delta specs exist, always run the sync assessment and show the combined summary before prompting

.cursor/commands/opsx-explore.md

@@ -0,0 +1,173 @@
+---
+name: /opsx-explore
+id: opsx-explore
+category: Workflow
+description: "Enter explore mode - think through ideas, investigate problems, clarify requirements"
+---
+
+Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
+
+**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing.
+
+**This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.
+
+**Input**: The argument after `/opsx:explore` is whatever the user wants to think about. Could be:
+- A vague idea: "real-time collaboration"
+- A specific problem: "the auth system is getting unwieldy"
+- A change name: "add-dark-mode" (to explore in context of that change)
+- A comparison: "postgres vs sqlite for this"
+- Nothing (just enter explore mode)
+
+---
+
+## The Stance
+
+- **Curious, not prescriptive** - Ask questions that emerge naturally, don't follow a script
+- **Open threads, not interrogations** - Surface multiple interesting directions and let the user follow what resonates. Don't funnel them through a single path of questions.
+- **Visual** - Use ASCII diagrams liberally when they'd help clarify thinking
+- **Adaptive** - Follow interesting threads, pivot when new information emerges
+- **Patient** - Don't rush to conclusions, let the shape of the problem emerge
+- **Grounded** - Explore the actual codebase when relevant, don't just theorize
+
+---
+
+## What You Might Do
+
+Depending on what the user brings, you might:
+
+**Explore the problem space**
+- Ask clarifying questions that emerge from what they said
+- Challenge assumptions
+- Reframe the problem
+- Find analogies
+
+**Investigate the codebase**
+- Map existing architecture relevant to the discussion
+- Find integration points
+- Identify patterns already in use
+- Surface hidden complexity
+
+**Compare options**
+- Brainstorm multiple approaches
+- Build comparison tables
+- Sketch tradeoffs
+- Recommend a path (if asked)
+
+**Visualize**
+```
+┌─────────────────────────────────────────┐
+│     Use ASCII diagrams liberally        │
+├─────────────────────────────────────────┤
+│                                         │
+│   ┌────────┐         ┌────────┐        │
+│   │ State  │────────▶│ State  │        │
+│   │   A    │         │   B    │        │
+│   └────────┘         └────────┘        │
+│                                         │
+│   System diagrams, state machines,      │
+│   data flows, architecture sketches,    │
+│   dependency graphs, comparison tables  │
+│                                         │
+└─────────────────────────────────────────┘
+```
+
+**Surface risks and unknowns**
+- Identify what could go wrong
+- Find gaps in understanding
+- Suggest spikes or investigations
+
+---
+
+## OpenSpec Awareness
+
+You have full context of the OpenSpec system. Use it naturally, don't force it.
+
+### Check for context
+
+At the start, quickly check what exists:
+```bash
+openspec list --json
+```
+
+This tells you:
+- If there are active changes
+- Their names, schemas, and status
+- What the user might be working on
+
+If the user mentioned a specific change name, read its artifacts for context.
+
+### When no change exists
+
+Think freely. When insights crystallize, you might offer:
+
+- "This feels solid enough to start a change. Want me to create a proposal?"
+- Or keep exploring - no pressure to formalize
+
+### When a change exists
+
+If the user mentions a change or you detect one is relevant:
+
+1. **Read existing artifacts for context**
+   - `openspec/changes/<name>/proposal.md`
+   - `openspec/changes/<name>/design.md`
+   - `openspec/changes/<name>/tasks.md`
+   - etc.
+
+2. **Reference them naturally in conversation**
+   - "Your design mentions using Redis, but we just realized SQLite fits better..."
+   - "The proposal scopes this to premium users, but we're now thinking everyone..."
+
+3. **Offer to capture when decisions are made**
+
+   | Insight Type | Where to Capture |
+   |--------------|------------------|
+   | New requirement discovered | `specs/<capability>/spec.md` |
+   | Requirement changed | `specs/<capability>/spec.md` |
+   | Design decision made | `design.md` |
+   | Scope changed | `proposal.md` |
+   | New work identified | `tasks.md` |
+   | Assumption invalidated | Relevant artifact |
+
+   Example offers:
+   - "That's a design decision. Capture it in design.md?"
+   - "This is a new requirement. Add it to specs?"
+   - "This changes scope. Update the proposal?"
+
+4. **The user decides** - Offer and move on. Don't pressure. Don't auto-capture.
+
+---
+
+## What You Don't Have To Do
+
+- Follow a script
+- Ask the same questions every time
+- Produce a specific artifact
+- Reach a conclusion
+- Stay on topic if a tangent is valuable
+- Be brief (this is thinking time)
+
+---
+
+## Ending Discovery
+
+There's no required ending. Discovery might:
+
+- **Flow into a proposal**: "Ready to start? I can create a change proposal."
+- **Result in artifact updates**: "Updated design.md with these decisions"
+- **Just provide clarity**: User has what they need, moves on
+- **Continue later**: "We can pick this up anytime"
+
+When things crystallize, you might offer a summary - but it's optional. Sometimes the thinking IS the value.
+
+---
+
+## Guardrails
+
+- **Don't implement** - Never write code or implement features. Creating OpenSpec artifacts is fine, writing application code is not.
+- **Don't fake understanding** - If something is unclear, dig deeper
+- **Don't rush** - Discovery is thinking time, not task time
+- **Don't force structure** - Let patterns emerge naturally
+- **Don't auto-capture** - Offer to save insights, don't just do it
+- **Do visualize** - A good diagram is worth many paragraphs
+- **Do explore the codebase** - Ground discussions in reality
+- **Do question assumptions** - Including the user's and your own

.cursor/commands/opsx-propose.md

@@ -0,0 +1,106 @@
+---
+name: /opsx-propose
+id: opsx-propose
+category: Workflow
+description: Propose a new change - create it and generate all artifacts in one step
+---
+
+Propose a new change - create the change and generate all artifacts in one step.
+
+I'll create a change with artifacts:
+- proposal.md (what & why)
+- design.md (how)
+- tasks.md (implementation steps)
+
+When ready to implement, run /opsx:apply
+
+---
+
+**Input**: The argument after `/opsx:propose` is the change name (kebab-case), OR a description of what the user wants to build.
+
+**Steps**
+
+1. **If no input provided, ask what they want to build**
+
+   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+   > "What change do you want to work on? Describe what you want to build or fix."
+
+   From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
+
+   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
+
+2. **Create the change directory**
+   ```bash
+   openspec new change "<name>"
+   ```
+   This creates a scaffolded change at `openspec/changes/<name>/` with `.openspec.yaml`.
+
+3. **Get the artifact build order**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to get:
+   - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
+   - `artifacts`: list of all artifacts with their status and dependencies
+
+4. **Create artifacts in sequence until apply-ready**
+
+   Use the **TodoWrite tool** to track progress through the artifacts.
+
+   Loop through artifacts in dependency order (artifacts with no pending dependencies first):
+
+   a. **For each artifact that is `ready` (dependencies satisfied)**:
+      - Get instructions:
+        ```bash
+        openspec instructions <artifact-id> --change "<name>" --json
+        ```
+      - The instructions JSON includes:
+        - `context`: Project background (constraints for you - do NOT include in output)
+        - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
+        - `template`: The structure to use for your output file
+        - `instruction`: Schema-specific guidance for this artifact type
+        - `outputPath`: Where to write the artifact
+        - `dependencies`: Completed artifacts to read for context
+      - Read any completed dependency files for context
+      - Create the artifact file using `template` as the structure
+      - Apply `context` and `rules` as constraints - but do NOT copy them into the file
+      - Show brief progress: "Created <artifact-id>"
+
+   b. **Continue until all `applyRequires` artifacts are complete**
+      - After creating each artifact, re-run `openspec status --change "<name>" --json`
+      - Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array
+      - Stop when all `applyRequires` artifacts are done
+
+   c. **If an artifact requires user input** (unclear context):
+      - Use **AskUserQuestion tool** to clarify
+      - Then continue with creation
+
+5. **Show final status**
+   ```bash
+   openspec status --change "<name>"
+   ```
+
+**Output**
+
+After completing all artifacts, summarize:
+- Change name and location
+- List of artifacts created with brief descriptions
+- What's ready: "All artifacts created! Ready for implementation."
+- Prompt: "Run `/opsx:apply` to start implementing."
+
+**Artifact Creation Guidelines**
+
+- Follow the `instruction` field from `openspec instructions` for each artifact type
+- The schema defines what each artifact should contain - follow it
+- Read dependency artifacts for context before creating new ones
+- Use `template` as the structure for your output file - fill in its sections
+- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
+  - Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
+  - These guide what you write, but should never appear in the output
+
+**Guardrails**
+- Create ALL artifacts needed for implementation (as defined by schema's `apply.requires`)
+- Always read dependency artifacts before creating a new one
+- If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
+- If a change with that name already exists, ask if user wants to continue it or create a new one
+- Verify each artifact file exists after writing before proceeding to next

.cursor/skills/openspec-apply-change/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: openspec-apply-change
+description: Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.2.0"
+---
+
+Implement tasks from an OpenSpec change.
+
+**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **Select the change**
+
+   If a name is provided, use it. Otherwise:
+   - Infer from conversation context if the user mentioned a change
+   - Auto-select if only one active change exists
+   - If ambiguous, run `openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select
+
+   Always announce: "Using change: <name>" and how to override (e.g., `/opsx:apply <other>`).
+
+2. **Check status to understand the schema**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used (e.g., "spec-driven")
+   - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
+
+3. **Get apply instructions**
+
+   ```bash
+   openspec instructions apply --change "<name>" --json
+   ```
+
+   This returns:
+   - Context 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 the files listed in `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

.cursor/skills/openspec-archive-change/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: openspec-archive-change
+description: Archive a completed change in the experimental workflow. Use when the user wants to finalize and archive a change after implementation is complete.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.2.0"
+---
+
+Archive a completed change in the experimental workflow.
+
+**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+
+   Show only active changes (not already archived).
+   Include the schema used for each change if available.
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Check artifact completion status**
+
+   Run `openspec status --change "<name>" --json` to check artifact completion.
+
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used
+   - `artifacts`: List of artifacts with their status (`done` or other)
+
+   **If any artifacts are not `done`:**
+   - Display warning listing incomplete artifacts
+   - Use **AskUserQuestion tool** to confirm user wants to proceed
+   - Proceed if user confirms
+
+3. **Check task completion status**
+
+   Read the tasks file (typically `tasks.md`) to check for incomplete tasks.
+
+   Count tasks marked with `- [ ]` (incomplete) vs `- [x]` (complete).
+
+   **If incomplete tasks found:**
+   - Display warning showing count of incomplete tasks
+   - Use **AskUserQuestion tool** to confirm user wants to proceed
+   - Proceed if user confirms
+
+   **If no tasks file exists:** Proceed without task-related warning.
+
+4. **Assess delta spec sync state**
+
+   Check for delta specs at `openspec/changes/<name>/specs/`. If none exist, proceed without sync prompt.
+
+   **If delta specs exist:**
+   - Compare each delta spec with its corresponding main spec at `openspec/specs/<capability>/spec.md`
+   - Determine what changes would be applied (adds, modifications, removals, renames)
+   - Show a combined summary before prompting
+
+   **Prompt options:**
+   - If changes needed: "Sync now (recommended)", "Archive without syncing"
+   - If already synced: "Archive now", "Sync anyway", "Cancel"
+
+   If user chooses sync, use Task tool (subagent_type: "general-purpose", prompt: "Use Skill tool to invoke openspec-sync-specs for change '<name>'. Delta spec analysis: <include the analyzed delta spec summary>"). Proceed to archive regardless of choice.
+
+5. **Perform the archive**
+
+   Create the archive directory if it doesn't exist:
+   ```bash
+   mkdir -p openspec/changes/archive
+   ```
+
+   Generate target name using current date: `YYYY-MM-DD-<change-name>`
+
+   **Check if target already exists:**
+   - If yes: Fail with error, suggest renaming existing archive or using different date
+   - If no: Move the change directory to archive
+
+   ```bash
+   mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
+   ```
+
+6. **Display summary**
+
+   Show archive completion summary including:
+   - Change name
+   - Schema that was used
+   - Archive location
+   - Whether specs were synced (if applicable)
+   - Note about any warnings (incomplete artifacts/tasks)
+
+**Output On Success**
+
+```
+## Archive Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** ✓ Synced to main specs (or "No delta specs" or "Sync skipped")
+
+All artifacts complete. All tasks complete.
+```
+
+**Guardrails**
+- Always prompt for change selection if not provided
+- Use artifact graph (openspec status --json) for completion checking
+- Don't block archive on warnings - just inform and confirm
+- Preserve .openspec.yaml when moving to archive (it moves with the directory)
+- Show clear summary of what happened
+- If sync is requested, use openspec-sync-specs approach (agent-driven)
+- If delta specs exist, always run the sync assessment and show the combined summary before prompting

.cursor/skills/openspec-explore/SKILL.md

@@ -0,0 +1,288 @@
+---
+name: openspec-explore
+description: Enter explore mode - a thinking partner for exploring ideas, investigating problems, and clarifying requirements. Use when the user wants to think through something before or during a change.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.2.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.
+
+---
+
+## The Stance
+
+- **Curious, not prescriptive** - Ask questions that emerge naturally, don't follow a script
+- **Open threads, not interrogations** - Surface multiple interesting directions and let the user follow what resonates. Don't funnel them through a single path of questions.
+- **Visual** - Use ASCII diagrams liberally when they'd help clarify thinking
+- **Adaptive** - Follow interesting threads, pivot when new information emerges
+- **Patient** - Don't rush to conclusions, let the shape of the problem emerge
+- **Grounded** - Explore the actual codebase when relevant, don't just theorize
+
+---
+
+## What You Might Do
+
+Depending on what the user brings, you might:
+
+**Explore the problem space**
+- Ask clarifying questions that emerge from what they said
+- Challenge assumptions
+- Reframe the problem
+- Find analogies
+
+**Investigate the codebase**
+- Map existing architecture relevant to the discussion
+- Find integration points
+- Identify patterns already in use
+- Surface hidden complexity
+
+**Compare options**
+- Brainstorm multiple approaches
+- Build comparison tables
+- Sketch tradeoffs
+- Recommend a path (if asked)
+
+**Visualize**
+```
+┌─────────────────────────────────────────┐
+│     Use ASCII diagrams liberally        │
+├─────────────────────────────────────────┤
+│                                         │
+│   ┌────────┐         ┌────────┐        │
+│   │ State  │────────▶│ State  │        │
+│   │   A    │         │   B    │        │
+│   └────────┘         └────────┘        │
+│                                         │
+│   System diagrams, state machines,      │
+│   data flows, architecture sketches,    │
+│   dependency graphs, comparison tables  │
+│                                         │
+└─────────────────────────────────────────┘
+```
+
+**Surface risks and unknowns**
+- Identify what could go wrong
+- Find gaps in understanding
+- Suggest spikes or investigations
+
+---
+
+## OpenSpec Awareness
+
+You have full context of the OpenSpec system. Use it naturally, don't force it.
+
+### Check for context
+
+At the start, quickly check what exists:
+```bash
+openspec list --json
+```
+
+This tells you:
+- If there are active changes
+- Their names, schemas, and status
+- What the user might be working on
+
+### When no change exists
+
+Think freely. When insights crystallize, you might offer:
+
+- "This feels solid enough to start a change. Want me to create a proposal?"
+- Or keep exploring - no pressure to formalize
+
+### When a change exists
+
+If the user mentions a change or you detect one is relevant:
+
+1. **Read existing artifacts for context**
+   - `openspec/changes/<name>/proposal.md`
+   - `openspec/changes/<name>/design.md`
+   - `openspec/changes/<name>/tasks.md`
+   - etc.
+
+2. **Reference them naturally in conversation**
+   - "Your design mentions using Redis, but we just realized SQLite fits better..."
+   - "The proposal scopes this to premium users, but we're now thinking everyone..."
+
+3. **Offer to capture when decisions are made**
+
+   | Insight Type | Where to Capture |
+   |--------------|------------------|
+   | New requirement discovered | `specs/<capability>/spec.md` |
+   | Requirement changed | `specs/<capability>/spec.md` |
+   | Design decision made | `design.md` |
+   | Scope changed | `proposal.md` |
+   | New work identified | `tasks.md` |
+   | Assumption invalidated | Relevant artifact |
+
+   Example offers:
+   - "That's a design decision. Capture it in design.md?"
+   - "This is a new requirement. Add it to specs?"
+   - "This changes scope. Update the proposal?"
+
+4. **The user decides** - Offer and move on. Don't pressure. Don't auto-capture.
+
+---
+
+## What You Don't Have To Do
+
+- Follow a script
+- Ask the same questions every time
+- Produce a specific artifact
+- Reach a conclusion
+- Stay on topic if a tangent is valuable
+- Be brief (this is thinking time)
+
+---
+
+## Handling Different Entry Points
+
+**User brings a vague idea:**
+```
+User: I'm thinking about adding real-time collaboration
+
+You: Real-time collab is a big space. Let me think about this...
+
+      COLLABORATION SPECTRUM
+      ════════════════════════════════════════════
+
+      Awareness          Coordination         Sync
+          │                   │                 │
+          ▼                   ▼                 ▼
+      ┌────────┐         ┌────────┐        ┌────────┐
+      │Presence│         │Cursors │        │  CRDT  │
+      │  "3    │         │ Multi  │        │Conflict│
+      │online" │         │ select │        │  free  │
+      └────────┘         └────────┘        └────────┘
+          │                   │                 │
+       trivial            moderate           complex
+
+      Where's your head at?
+```
+
+**User brings a specific problem:**
+```
+User: The auth system is a mess
+
+You: [reads codebase]
+
+     ┌─────────────────────────────────────────────┐
+     │              CURRENT AUTH FLOW              │
+     └─────────────────────────────────────────────┘
+                        │
+          ┌─────────────┼─────────────┐
+          ▼             ▼             ▼
+     ┌─────────┐  ┌─────────┐  ┌─────────┐
+     │ Google  │  │  GitHub │  │  Email  │
+     │  OAuth  │  │  OAuth  │  │  Magic  │
+     └────┬────┘  └────┬────┘  └────┬────┘
+          │             │             │
+          └─────────────┼─────────────┘
+                        ▼
+                  ┌───────────┐
+                  │  Session  │
+                  └─────┬─────┘
+                        │
+                        ▼
+                  ┌───────────┐
+                  │   Perms   │
+                  └───────────┘
+
+     I see three tangles. Which one's burning?
+```
+
+**User is stuck mid-implementation:**
+```
+User: /opsx:explore add-auth-system
+      The OAuth integration is more complex than expected
+
+You: [reads change artifacts]
+
+     You're on task 4: "Implement OAuth flow"
+
+     Let me trace what's involved...
+
+     [draws diagram, explores options, suggests paths]
+
+     Want to update the design to reflect this?
+     Or add a spike task to investigate?
+```
+
+**User wants to compare options:**
+```
+User: Should we use Postgres or SQLite?
+
+You: Generic answer is boring. What's the context?
+
+User: A CLI tool that tracks local dev environments
+
+You: That changes everything.
+
+     ┌─────────────────────────────────────────────────┐
+     │         CLI TOOL DATA STORAGE                  │
+     └─────────────────────────────────────────────────┘
+
+     Key constraints:
+     • No daemon running
+     • Must work offline
+     • Single user
+
+                  SQLite          Postgres
+     Deployment   embedded ✓      needs server ✗
+     Offline      yes ✓           no ✗
+     Single file  yes ✓           no ✗
+
+     SQLite. Not even close.
+
+     Unless... is there a sync component?
+```
+
+---
+
+## Ending Discovery
+
+There's no required ending. Discovery might:
+
+- **Flow into a proposal**: "Ready to start? I can create a change proposal."
+- **Result in artifact updates**: "Updated design.md with these decisions"
+- **Just provide clarity**: User has what they need, moves on
+- **Continue later**: "We can pick this up anytime"
+
+When it feels like things are crystallizing, you might summarize:
+
+```
+## What We Figured Out
+
+**The problem**: [crystallized understanding]
+
+**The approach**: [if one emerged]
+
+**Open questions**: [if any remain]
+
+**Next steps** (if ready):
+- Create a change proposal
+- Keep exploring: just keep talking
+```
+
+But this summary is optional. Sometimes the thinking IS the value.
+
+---
+
+## Guardrails
+
+- **Don't implement** - Never write code or implement features. Creating OpenSpec artifacts is fine, writing application code is not.
+- **Don't fake understanding** - If something is unclear, dig deeper
+- **Don't rush** - Discovery is thinking time, not task time
+- **Don't force structure** - Let patterns emerge naturally
+- **Don't auto-capture** - Offer to save insights, don't just do it
+- **Do visualize** - A good diagram is worth many paragraphs
+- **Do explore the codebase** - Ground discussions in reality
+- **Do question assumptions** - Including the user's and your own

.cursor/skills/openspec-propose/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: openspec-propose
+description: Propose a new change with all artifacts generated in one step. Use when the user wants to quickly describe what they want to build and get a complete proposal with design, specs, and tasks ready for implementation.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.2.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
+
+---
+
+**Input**: The user's request should include a change name (kebab-case) OR a description of what they want to build.
+
+**Steps**
+
+1. **If no clear input provided, ask what they want to build**
+
+   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+   > "What change do you want to work on? Describe what you want to build or fix."
+
+   From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
+
+   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
+
+2. **Create the change directory**
+   ```bash
+   openspec new change "<name>"
+   ```
+   This creates a scaffolded change at `openspec/changes/<name>/` with `.openspec.yaml`.
+
+3. **Get the artifact build order**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to get:
+   - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
+   - `artifacts`: list of all artifacts with their status and dependencies
+
+4. **Create artifacts in sequence until apply-ready**
+
+   Use the **TodoWrite tool** to track progress through the artifacts.
+
+   Loop through artifacts in dependency order (artifacts with no pending dependencies first):
+
+   a. **For each artifact that is `ready` (dependencies satisfied)**:
+      - Get instructions:
+        ```bash
+        openspec instructions <artifact-id> --change "<name>" --json
+        ```
+      - The instructions JSON includes:
+        - `context`: Project background (constraints for you - do NOT include in output)
+        - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
+        - `template`: The structure to use for your output file
+        - `instruction`: Schema-specific guidance for this artifact type
+        - `outputPath`: Where to write the artifact
+        - `dependencies`: Completed artifacts to read for context
+      - Read any completed dependency files for context
+      - Create the artifact file using `template` as the structure
+      - Apply `context` and `rules` as constraints - but do NOT copy them into the file
+      - Show brief progress: "Created <artifact-id>"
+
+   b. **Continue until all `applyRequires` artifacts are complete**
+      - After creating each artifact, re-run `openspec status --change "<name>" --json`
+      - Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array
+      - Stop when all `applyRequires` artifacts are done
+
+   c. **If an artifact requires user input** (unclear context):
+      - Use **AskUserQuestion tool** to clarify
+      - Then continue with creation
+
+5. **Show final status**
+   ```bash
+   openspec status --change "<name>"
+   ```
+
+**Output**
+
+After completing all artifacts, summarize:
+- Change name and location
+- List of artifacts created with brief descriptions
+- What's ready: "All artifacts created! Ready for implementation."
+- Prompt: "Run `/opsx:apply` or ask me to implement to start working on the tasks."
+
+**Artifact Creation Guidelines**
+
+- Follow the `instruction` field from `openspec instructions` for each artifact type
+- The schema defines what each artifact should contain - follow it
+- Read dependency artifacts for context before creating new ones
+- Use `template` as the structure for your output file - fill in its sections
+- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
+  - Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
+  - These guide what you write, but should never appear in the output
+
+**Guardrails**
+- Create ALL artifacts needed for implementation (as defined by schema's `apply.requires`)
+- Always read dependency artifacts before creating a new one
+- If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
+- If a change with that name already exists, ask if user wants to continue it or create a new one
+- Verify each artifact file exists after writing before proceeding to next

.env.example

@@ -21,11 +21,11 @@ API_BOOTSTRAP_TOKEN=change-me-in-production
 # =============================================================================
 
 # API Service
-API_LISTEN_ADDR=0.0.0.0:8080
-API_BASE_URL=http://api:8080
+API_LISTEN_ADDR=0.0.0.0:7080
+API_BASE_URL=http://api:7080
 
 # Indexer Service  
-INDEXER_LISTEN_ADDR=0.0.0.0:8081
+INDEXER_LISTEN_ADDR=0.0.0.0:7081
 INDEXER_SCAN_INTERVAL_SECONDS=5
 
 # Meilisearch Search Engine
@@ -56,8 +56,8 @@ THUMBNAILS_HOST_PATH=../data/thumbnails
 # Port Configuration
 # =============================================================================
 # To change ports, edit docker-compose.yml directly:
-# - API: change "7080:8080" to "YOUR_PORT:8080"
-# - Indexer: change "7081:8081" to "YOUR_PORT:8081"
-# - Backoffice: change "7082:8082" to "YOUR_PORT:8082"
+# - API: change "7080:7080" to "YOUR_PORT:7080"
+# - Indexer: change "7081:7081" to "YOUR_PORT:7081"
+# - Backoffice: change "7082:7082" to "YOUR_PORT:7082"
 # - Meilisearch: change "7700:7700" to "YOUR_PORT:7700"
 # - PostgreSQL: change "6432:5432" to "YOUR_PORT:5432"

.gitignore

@@ -2,7 +2,7 @@ target/
 .env
 .DS_Store
 tmp/
-libraries/
+/libraries/
 node_modules/
 .next/
 data/thumbnails

.opencode/command/opsx-apply.md

@@ -0,0 +1,149 @@
+---
+description: Implement tasks from an OpenSpec change (Experimental)
+---
+
+Implement tasks from an OpenSpec change.
+
+**Input**: Optionally specify a change name (e.g., `/opsx-apply add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **Select the change**
+
+   If a name is provided, use it. Otherwise:
+   - Infer from conversation context if the user mentioned a change
+   - Auto-select if only one active change exists
+   - If ambiguous, run `openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select
+
+   Always announce: "Using change: <name>" and how to override (e.g., `/opsx-apply <other>`).
+
+2. **Check status to understand the schema**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used (e.g., "spec-driven")
+   - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
+
+3. **Get apply instructions**
+
+   ```bash
+   openspec instructions apply --change "<name>" --json
+   ```
+
+   This returns:
+   - Context 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 the files listed in `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

.opencode/command/opsx-archive.md

@@ -0,0 +1,154 @@
+---
+description: Archive a completed change in the experimental workflow
+---
+
+Archive a completed change in the experimental workflow.
+
+**Input**: Optionally specify a change name after `/opsx-archive` (e.g., `/opsx-archive add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+
+   Show only active changes (not already archived).
+   Include the schema used for each change if available.
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Check artifact completion status**
+
+   Run `openspec status --change "<name>" --json` to check artifact completion.
+
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used
+   - `artifacts`: List of artifacts with their status (`done` or other)
+
+   **If any artifacts are not `done`:**
+   - Display warning listing incomplete artifacts
+   - Prompt user for confirmation to continue
+   - Proceed if user confirms
+
+3. **Check task completion status**
+
+   Read the tasks file (typically `tasks.md`) to check for incomplete tasks.
+
+   Count tasks marked with `- [ ]` (incomplete) vs `- [x]` (complete).
+
+   **If incomplete tasks found:**
+   - Display warning showing count of incomplete tasks
+   - Prompt user for confirmation to continue
+   - Proceed if user confirms
+
+   **If no tasks file exists:** Proceed without task-related warning.
+
+4. **Assess delta spec sync state**
+
+   Check for delta specs at `openspec/changes/<name>/specs/`. If none exist, proceed without sync prompt.
+
+   **If delta specs exist:**
+   - Compare each delta spec with its corresponding main spec at `openspec/specs/<capability>/spec.md`
+   - Determine what changes would be applied (adds, modifications, removals, renames)
+   - Show a combined summary before prompting
+
+   **Prompt options:**
+   - If changes needed: "Sync now (recommended)", "Archive without syncing"
+   - If already synced: "Archive now", "Sync anyway", "Cancel"
+
+   If user chooses sync, use Task tool (subagent_type: "general-purpose", prompt: "Use Skill tool to invoke openspec-sync-specs for change '<name>'. Delta spec analysis: <include the analyzed delta spec summary>"). Proceed to archive regardless of choice.
+
+5. **Perform the archive**
+
+   Create the archive directory if it doesn't exist:
+   ```bash
+   mkdir -p openspec/changes/archive
+   ```
+
+   Generate target name using current date: `YYYY-MM-DD-<change-name>`
+
+   **Check if target already exists:**
+   - If yes: Fail with error, suggest renaming existing archive or using different date
+   - If no: Move the change directory to archive
+
+   ```bash
+   mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
+   ```
+
+6. **Display summary**
+
+   Show archive completion summary including:
+   - Change name
+   - Schema that was used
+   - Archive location
+   - Spec sync status (synced / sync skipped / no delta specs)
+   - Note about any warnings (incomplete artifacts/tasks)
+
+**Output On Success**
+
+```
+## Archive Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** ✓ Synced to main specs
+
+All artifacts complete. All tasks complete.
+```
+
+**Output On Success (No Delta Specs)**
+
+```
+## Archive Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** No delta specs
+
+All artifacts complete. All tasks complete.
+```
+
+**Output On Success With Warnings**
+
+```
+## Archive Complete (with warnings)
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** Sync skipped (user chose to skip)
+
+**Warnings:**
+- Archived with 2 incomplete artifacts
+- Archived with 3 incomplete tasks
+- Delta spec sync was skipped (user chose to skip)
+
+Review the archive if this was not intentional.
+```
+
+**Output On Error (Archive Exists)**
+
+```
+## Archive Failed
+
+**Change:** <change-name>
+**Target:** openspec/changes/archive/YYYY-MM-DD-<name>/
+
+Target archive directory already exists.
+
+**Options:**
+1. Rename the existing archive
+2. Delete the existing archive if it's a duplicate
+3. Wait until a different date to archive
+```
+
+**Guardrails**
+- Always prompt for change selection if not provided
+- Use artifact graph (openspec status --json) for completion checking
+- Don't block archive on warnings - just inform and confirm
+- Preserve .openspec.yaml when moving to archive (it moves with the directory)
+- Show clear summary of what happened
+- If sync is requested, use the Skill tool to invoke `openspec-sync-specs` (agent-driven)
+- If delta specs exist, always run the sync assessment and show the combined summary before prompting

.opencode/command/opsx-explore.md

@@ -0,0 +1,170 @@
+---
+description: Enter explore mode - think through ideas, investigate problems, clarify requirements
+---
+
+Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
+
+**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing.
+
+**This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.
+
+**Input**: The argument after `/opsx-explore` is whatever the user wants to think about. Could be:
+- A vague idea: "real-time collaboration"
+- A specific problem: "the auth system is getting unwieldy"
+- A change name: "add-dark-mode" (to explore in context of that change)
+- A comparison: "postgres vs sqlite for this"
+- Nothing (just enter explore mode)
+
+---
+
+## The Stance
+
+- **Curious, not prescriptive** - Ask questions that emerge naturally, don't follow a script
+- **Open threads, not interrogations** - Surface multiple interesting directions and let the user follow what resonates. Don't funnel them through a single path of questions.
+- **Visual** - Use ASCII diagrams liberally when they'd help clarify thinking
+- **Adaptive** - Follow interesting threads, pivot when new information emerges
+- **Patient** - Don't rush to conclusions, let the shape of the problem emerge
+- **Grounded** - Explore the actual codebase when relevant, don't just theorize
+
+---
+
+## What You Might Do
+
+Depending on what the user brings, you might:
+
+**Explore the problem space**
+- Ask clarifying questions that emerge from what they said
+- Challenge assumptions
+- Reframe the problem
+- Find analogies
+
+**Investigate the codebase**
+- Map existing architecture relevant to the discussion
+- Find integration points
+- Identify patterns already in use
+- Surface hidden complexity
+
+**Compare options**
+- Brainstorm multiple approaches
+- Build comparison tables
+- Sketch tradeoffs
+- Recommend a path (if asked)
+
+**Visualize**
+```
+┌─────────────────────────────────────────┐
+│     Use ASCII diagrams liberally        │
+├─────────────────────────────────────────┤
+│                                         │
+│   ┌────────┐         ┌────────┐        │
+│   │ State  │────────▶│ State  │        │
+│   │   A    │         │   B    │        │
+│   └────────┘         └────────┘        │
+│                                         │
+│   System diagrams, state machines,      │
+│   data flows, architecture sketches,    │
+│   dependency graphs, comparison tables  │
+│                                         │
+└─────────────────────────────────────────┘
+```
+
+**Surface risks and unknowns**
+- Identify what could go wrong
+- Find gaps in understanding
+- Suggest spikes or investigations
+
+---
+
+## OpenSpec Awareness
+
+You have full context of the OpenSpec system. Use it naturally, don't force it.
+
+### Check for context
+
+At the start, quickly check what exists:
+```bash
+openspec list --json
+```
+
+This tells you:
+- If there are active changes
+- Their names, schemas, and status
+- What the user might be working on
+
+If the user mentioned a specific change name, read its artifacts for context.
+
+### When no change exists
+
+Think freely. When insights crystallize, you might offer:
+
+- "This feels solid enough to start a change. Want me to create a proposal?"
+- Or keep exploring - no pressure to formalize
+
+### When a change exists
+
+If the user mentions a change or you detect one is relevant:
+
+1. **Read existing artifacts for context**
+   - `openspec/changes/<name>/proposal.md`
+   - `openspec/changes/<name>/design.md`
+   - `openspec/changes/<name>/tasks.md`
+   - etc.
+
+2. **Reference them naturally in conversation**
+   - "Your design mentions using Redis, but we just realized SQLite fits better..."
+   - "The proposal scopes this to premium users, but we're now thinking everyone..."
+
+3. **Offer to capture when decisions are made**
+
+   | Insight Type | Where to Capture |
+   |--------------|------------------|
+   | New requirement discovered | `specs/<capability>/spec.md` |
+   | Requirement changed | `specs/<capability>/spec.md` |
+   | Design decision made | `design.md` |
+   | Scope changed | `proposal.md` |
+   | New work identified | `tasks.md` |
+   | Assumption invalidated | Relevant artifact |
+
+   Example offers:
+   - "That's a design decision. Capture it in design.md?"
+   - "This is a new requirement. Add it to specs?"
+   - "This changes scope. Update the proposal?"
+
+4. **The user decides** - Offer and move on. Don't pressure. Don't auto-capture.
+
+---
+
+## What You Don't Have To Do
+
+- Follow a script
+- Ask the same questions every time
+- Produce a specific artifact
+- Reach a conclusion
+- Stay on topic if a tangent is valuable
+- Be brief (this is thinking time)
+
+---
+
+## Ending Discovery
+
+There's no required ending. Discovery might:
+
+- **Flow into a proposal**: "Ready to start? I can create a change proposal."
+- **Result in artifact updates**: "Updated design.md with these decisions"
+- **Just provide clarity**: User has what they need, moves on
+- **Continue later**: "We can pick this up anytime"
+
+When things crystallize, you might offer a summary - but it's optional. Sometimes the thinking IS the value.
+
+---
+
+## Guardrails
+
+- **Don't implement** - Never write code or implement features. Creating OpenSpec artifacts is fine, writing application code is not.
+- **Don't fake understanding** - If something is unclear, dig deeper
+- **Don't rush** - Discovery is thinking time, not task time
+- **Don't force structure** - Let patterns emerge naturally
+- **Don't auto-capture** - Offer to save insights, don't just do it
+- **Do visualize** - A good diagram is worth many paragraphs
+- **Do explore the codebase** - Ground discussions in reality
+- **Do question assumptions** - Including the user's and your own

.opencode/command/opsx-propose.md

@@ -0,0 +1,103 @@
+---
+description: Propose a new change - create it and generate all artifacts in one step
+---
+
+Propose a new change - create the change and generate all artifacts in one step.
+
+I'll create a change with artifacts:
+- proposal.md (what & why)
+- design.md (how)
+- tasks.md (implementation steps)
+
+When ready to implement, run /opsx-apply
+
+---
+
+**Input**: The argument after `/opsx-propose` is the change name (kebab-case), OR a description of what the user wants to build.
+
+**Steps**
+
+1. **If no input provided, ask what they want to build**
+
+   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+   > "What change do you want to work on? Describe what you want to build or fix."
+
+   From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
+
+   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
+
+2. **Create the change directory**
+   ```bash
+   openspec new change "<name>"
+   ```
+   This creates a scaffolded change at `openspec/changes/<name>/` with `.openspec.yaml`.
+
+3. **Get the artifact build order**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to get:
+   - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
+   - `artifacts`: list of all artifacts with their status and dependencies
+
+4. **Create artifacts in sequence until apply-ready**
+
+   Use the **TodoWrite tool** to track progress through the artifacts.
+
+   Loop through artifacts in dependency order (artifacts with no pending dependencies first):
+
+   a. **For each artifact that is `ready` (dependencies satisfied)**:
+      - Get instructions:
+        ```bash
+        openspec instructions <artifact-id> --change "<name>" --json
+        ```
+      - The instructions JSON includes:
+        - `context`: Project background (constraints for you - do NOT include in output)
+        - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
+        - `template`: The structure to use for your output file
+        - `instruction`: Schema-specific guidance for this artifact type
+        - `outputPath`: Where to write the artifact
+        - `dependencies`: Completed artifacts to read for context
+      - Read any completed dependency files for context
+      - Create the artifact file using `template` as the structure
+      - Apply `context` and `rules` as constraints - but do NOT copy them into the file
+      - Show brief progress: "Created <artifact-id>"
+
+   b. **Continue until all `applyRequires` artifacts are complete**
+      - After creating each artifact, re-run `openspec status --change "<name>" --json`
+      - Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array
+      - Stop when all `applyRequires` artifacts are done
+
+   c. **If an artifact requires user input** (unclear context):
+      - Use **AskUserQuestion tool** to clarify
+      - Then continue with creation
+
+5. **Show final status**
+   ```bash
+   openspec status --change "<name>"
+   ```
+
+**Output**
+
+After completing all artifacts, summarize:
+- Change name and location
+- List of artifacts created with brief descriptions
+- What's ready: "All artifacts created! Ready for implementation."
+- Prompt: "Run `/opsx-apply` to start implementing."
+
+**Artifact Creation Guidelines**
+
+- Follow the `instruction` field from `openspec instructions` for each artifact type
+- The schema defines what each artifact should contain - follow it
+- Read dependency artifacts for context before creating new ones
+- Use `template` as the structure for your output file - fill in its sections
+- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
+  - Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
+  - These guide what you write, but should never appear in the output
+
+**Guardrails**
+- Create ALL artifacts needed for implementation (as defined by schema's `apply.requires`)
+- Always read dependency artifacts before creating a new one
+- If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
+- If a change with that name already exists, ask if user wants to continue it or create a new one
+- Verify each artifact file exists after writing before proceeding to next

.opencode/skills/openspec-apply-change/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: openspec-apply-change
+description: Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.2.0"
+---
+
+Implement tasks from an OpenSpec change.
+
+**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **Select the change**
+
+   If a name is provided, use it. Otherwise:
+   - Infer from conversation context if the user mentioned a change
+   - Auto-select if only one active change exists
+   - If ambiguous, run `openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select
+
+   Always announce: "Using change: <name>" and how to override (e.g., `/opsx-apply <other>`).
+
+2. **Check status to understand the schema**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used (e.g., "spec-driven")
+   - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
+
+3. **Get apply instructions**
+
+   ```bash
+   openspec instructions apply --change "<name>" --json
+   ```
+
+   This returns:
+   - Context 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 the files listed in `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

.opencode/skills/openspec-archive-change/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: openspec-archive-change
+description: Archive a completed change in the experimental workflow. Use when the user wants to finalize and archive a change after implementation is complete.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.2.0"
+---
+
+Archive a completed change in the experimental workflow.
+
+**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+
+   Show only active changes (not already archived).
+   Include the schema used for each change if available.
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Check artifact completion status**
+
+   Run `openspec status --change "<name>" --json` to check artifact completion.
+
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used
+   - `artifacts`: List of artifacts with their status (`done` or other)
+
+   **If any artifacts are not `done`:**
+   - Display warning listing incomplete artifacts
+   - Use **AskUserQuestion tool** to confirm user wants to proceed
+   - Proceed if user confirms
+
+3. **Check task completion status**
+
+   Read the tasks file (typically `tasks.md`) to check for incomplete tasks.
+
+   Count tasks marked with `- [ ]` (incomplete) vs `- [x]` (complete).
+
+   **If incomplete tasks found:**
+   - Display warning showing count of incomplete tasks
+   - Use **AskUserQuestion tool** to confirm user wants to proceed
+   - Proceed if user confirms
+
+   **If no tasks file exists:** Proceed without task-related warning.
+
+4. **Assess delta spec sync state**
+
+   Check for delta specs at `openspec/changes/<name>/specs/`. If none exist, proceed without sync prompt.
+
+   **If delta specs exist:**
+   - Compare each delta spec with its corresponding main spec at `openspec/specs/<capability>/spec.md`
+   - Determine what changes would be applied (adds, modifications, removals, renames)
+   - Show a combined summary before prompting
+
+   **Prompt options:**
+   - If changes needed: "Sync now (recommended)", "Archive without syncing"
+   - If already synced: "Archive now", "Sync anyway", "Cancel"
+
+   If user chooses sync, use Task tool (subagent_type: "general-purpose", prompt: "Use Skill tool to invoke openspec-sync-specs for change '<name>'. Delta spec analysis: <include the analyzed delta spec summary>"). Proceed to archive regardless of choice.
+
+5. **Perform the archive**
+
+   Create the archive directory if it doesn't exist:
+   ```bash
+   mkdir -p openspec/changes/archive
+   ```
+
+   Generate target name using current date: `YYYY-MM-DD-<change-name>`
+
+   **Check if target already exists:**
+   - If yes: Fail with error, suggest renaming existing archive or using different date
+   - If no: Move the change directory to archive
+
+   ```bash
+   mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
+   ```
+
+6. **Display summary**
+
+   Show archive completion summary including:
+   - Change name
+   - Schema that was used
+   - Archive location
+   - Whether specs were synced (if applicable)
+   - Note about any warnings (incomplete artifacts/tasks)
+
+**Output On Success**
+
+```
+## Archive Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** ✓ Synced to main specs (or "No delta specs" or "Sync skipped")
+
+All artifacts complete. All tasks complete.
+```
+
+**Guardrails**
+- Always prompt for change selection if not provided
+- Use artifact graph (openspec status --json) for completion checking
+- Don't block archive on warnings - just inform and confirm
+- Preserve .openspec.yaml when moving to archive (it moves with the directory)
+- Show clear summary of what happened
+- If sync is requested, use openspec-sync-specs approach (agent-driven)
+- If delta specs exist, always run the sync assessment and show the combined summary before prompting

.opencode/skills/openspec-explore/SKILL.md

@@ -0,0 +1,288 @@
+---
+name: openspec-explore
+description: Enter explore mode - a thinking partner for exploring ideas, investigating problems, and clarifying requirements. Use when the user wants to think through something before or during a change.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.2.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.
+
+---
+
+## The Stance
+
+- **Curious, not prescriptive** - Ask questions that emerge naturally, don't follow a script
+- **Open threads, not interrogations** - Surface multiple interesting directions and let the user follow what resonates. Don't funnel them through a single path of questions.
+- **Visual** - Use ASCII diagrams liberally when they'd help clarify thinking
+- **Adaptive** - Follow interesting threads, pivot when new information emerges
+- **Patient** - Don't rush to conclusions, let the shape of the problem emerge
+- **Grounded** - Explore the actual codebase when relevant, don't just theorize
+
+---
+
+## What You Might Do
+
+Depending on what the user brings, you might:
+
+**Explore the problem space**
+- Ask clarifying questions that emerge from what they said
+- Challenge assumptions
+- Reframe the problem
+- Find analogies
+
+**Investigate the codebase**
+- Map existing architecture relevant to the discussion
+- Find integration points
+- Identify patterns already in use
+- Surface hidden complexity
+
+**Compare options**
+- Brainstorm multiple approaches
+- Build comparison tables
+- Sketch tradeoffs
+- Recommend a path (if asked)
+
+**Visualize**
+```
+┌─────────────────────────────────────────┐
+│     Use ASCII diagrams liberally        │
+├─────────────────────────────────────────┤
+│                                         │
+│   ┌────────┐         ┌────────┐        │
+│   │ State  │────────▶│ State  │        │
+│   │   A    │         │   B    │        │
+│   └────────┘         └────────┘        │
+│                                         │
+│   System diagrams, state machines,      │
+│   data flows, architecture sketches,    │
+│   dependency graphs, comparison tables  │
+│                                         │
+└─────────────────────────────────────────┘
+```
+
+**Surface risks and unknowns**
+- Identify what could go wrong
+- Find gaps in understanding
+- Suggest spikes or investigations
+
+---
+
+## OpenSpec Awareness
+
+You have full context of the OpenSpec system. Use it naturally, don't force it.
+
+### Check for context
+
+At the start, quickly check what exists:
+```bash
+openspec list --json
+```
+
+This tells you:
+- If there are active changes
+- Their names, schemas, and status
+- What the user might be working on
+
+### When no change exists
+
+Think freely. When insights crystallize, you might offer:
+
+- "This feels solid enough to start a change. Want me to create a proposal?"
+- Or keep exploring - no pressure to formalize
+
+### When a change exists
+
+If the user mentions a change or you detect one is relevant:
+
+1. **Read existing artifacts for context**
+   - `openspec/changes/<name>/proposal.md`
+   - `openspec/changes/<name>/design.md`
+   - `openspec/changes/<name>/tasks.md`
+   - etc.
+
+2. **Reference them naturally in conversation**
+   - "Your design mentions using Redis, but we just realized SQLite fits better..."
+   - "The proposal scopes this to premium users, but we're now thinking everyone..."
+
+3. **Offer to capture when decisions are made**
+
+   | Insight Type | Where to Capture |
+   |--------------|------------------|
+   | New requirement discovered | `specs/<capability>/spec.md` |
+   | Requirement changed | `specs/<capability>/spec.md` |
+   | Design decision made | `design.md` |
+   | Scope changed | `proposal.md` |
+   | New work identified | `tasks.md` |
+   | Assumption invalidated | Relevant artifact |
+
+   Example offers:
+   - "That's a design decision. Capture it in design.md?"
+   - "This is a new requirement. Add it to specs?"
+   - "This changes scope. Update the proposal?"
+
+4. **The user decides** - Offer and move on. Don't pressure. Don't auto-capture.
+
+---
+
+## What You Don't Have To Do
+
+- Follow a script
+- Ask the same questions every time
+- Produce a specific artifact
+- Reach a conclusion
+- Stay on topic if a tangent is valuable
+- Be brief (this is thinking time)
+
+---
+
+## Handling Different Entry Points
+
+**User brings a vague idea:**
+```
+User: I'm thinking about adding real-time collaboration
+
+You: Real-time collab is a big space. Let me think about this...
+
+      COLLABORATION SPECTRUM
+      ════════════════════════════════════════════
+
+      Awareness          Coordination         Sync
+          │                   │                 │
+          ▼                   ▼                 ▼
+      ┌────────┐         ┌────────┐        ┌────────┐
+      │Presence│         │Cursors │        │  CRDT  │
+      │  "3    │         │ Multi  │        │Conflict│
+      │online" │         │ select │        │  free  │
+      └────────┘         └────────┘        └────────┘
+          │                   │                 │
+       trivial            moderate           complex
+
+      Where's your head at?
+```
+
+**User brings a specific problem:**
+```
+User: The auth system is a mess
+
+You: [reads codebase]
+
+     ┌─────────────────────────────────────────────┐
+     │              CURRENT AUTH FLOW              │
+     └─────────────────────────────────────────────┘
+                        │
+          ┌─────────────┼─────────────┐
+          ▼             ▼             ▼
+     ┌─────────┐  ┌─────────┐  ┌─────────┐
+     │ Google  │  │  GitHub │  │  Email  │
+     │  OAuth  │  │  OAuth  │  │  Magic  │
+     └────┬────┘  └────┬────┘  └────┬────┘
+          │             │             │
+          └─────────────┼─────────────┘
+                        ▼
+                  ┌───────────┐
+                  │  Session  │
+                  └─────┬─────┘
+                        │
+                        ▼
+                  ┌───────────┐
+                  │   Perms   │
+                  └───────────┘
+
+     I see three tangles. Which one's burning?
+```
+
+**User is stuck mid-implementation:**
+```
+User: /opsx-explore add-auth-system
+      The OAuth integration is more complex than expected
+
+You: [reads change artifacts]
+
+     You're on task 4: "Implement OAuth flow"
+
+     Let me trace what's involved...
+
+     [draws diagram, explores options, suggests paths]
+
+     Want to update the design to reflect this?
+     Or add a spike task to investigate?
+```
+
+**User wants to compare options:**
+```
+User: Should we use Postgres or SQLite?
+
+You: Generic answer is boring. What's the context?
+
+User: A CLI tool that tracks local dev environments
+
+You: That changes everything.
+
+     ┌─────────────────────────────────────────────────┐
+     │         CLI TOOL DATA STORAGE                  │
+     └─────────────────────────────────────────────────┘
+
+     Key constraints:
+     • No daemon running
+     • Must work offline
+     • Single user
+
+                  SQLite          Postgres
+     Deployment   embedded ✓      needs server ✗
+     Offline      yes ✓           no ✗
+     Single file  yes ✓           no ✗
+
+     SQLite. Not even close.
+
+     Unless... is there a sync component?
+```
+
+---
+
+## Ending Discovery
+
+There's no required ending. Discovery might:
+
+- **Flow into a proposal**: "Ready to start? I can create a change proposal."
+- **Result in artifact updates**: "Updated design.md with these decisions"
+- **Just provide clarity**: User has what they need, moves on
+- **Continue later**: "We can pick this up anytime"
+
+When it feels like things are crystallizing, you might summarize:
+
+```
+## What We Figured Out
+
+**The problem**: [crystallized understanding]
+
+**The approach**: [if one emerged]
+
+**Open questions**: [if any remain]
+
+**Next steps** (if ready):
+- Create a change proposal
+- Keep exploring: just keep talking
+```
+
+But this summary is optional. Sometimes the thinking IS the value.
+
+---
+
+## Guardrails
+
+- **Don't implement** - Never write code or implement features. Creating OpenSpec artifacts is fine, writing application code is not.
+- **Don't fake understanding** - If something is unclear, dig deeper
+- **Don't rush** - Discovery is thinking time, not task time
+- **Don't force structure** - Let patterns emerge naturally
+- **Don't auto-capture** - Offer to save insights, don't just do it
+- **Do visualize** - A good diagram is worth many paragraphs
+- **Do explore the codebase** - Ground discussions in reality
+- **Do question assumptions** - Including the user's and your own

.opencode/skills/openspec-propose/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: openspec-propose
+description: Propose a new change with all artifacts generated in one step. Use when the user wants to quickly describe what they want to build and get a complete proposal with design, specs, and tasks ready for implementation.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.2.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
+
+---
+
+**Input**: The user's request should include a change name (kebab-case) OR a description of what they want to build.
+
+**Steps**
+
+1. **If no clear input provided, ask what they want to build**
+
+   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+   > "What change do you want to work on? Describe what you want to build or fix."
+
+   From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
+
+   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
+
+2. **Create the change directory**
+   ```bash
+   openspec new change "<name>"
+   ```
+   This creates a scaffolded change at `openspec/changes/<name>/` with `.openspec.yaml`.
+
+3. **Get the artifact build order**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to get:
+   - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
+   - `artifacts`: list of all artifacts with their status and dependencies
+
+4. **Create artifacts in sequence until apply-ready**
+
+   Use the **TodoWrite tool** to track progress through the artifacts.
+
+   Loop through artifacts in dependency order (artifacts with no pending dependencies first):
+
+   a. **For each artifact that is `ready` (dependencies satisfied)**:
+      - Get instructions:
+        ```bash
+        openspec instructions <artifact-id> --change "<name>" --json
+        ```
+      - The instructions JSON includes:
+        - `context`: Project background (constraints for you - do NOT include in output)
+        - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
+        - `template`: The structure to use for your output file
+        - `instruction`: Schema-specific guidance for this artifact type
+        - `outputPath`: Where to write the artifact
+        - `dependencies`: Completed artifacts to read for context
+      - Read any completed dependency files for context
+      - Create the artifact file using `template` as the structure
+      - Apply `context` and `rules` as constraints - but do NOT copy them into the file
+      - Show brief progress: "Created <artifact-id>"
+
+   b. **Continue until all `applyRequires` artifacts are complete**
+      - After creating each artifact, re-run `openspec status --change "<name>" --json`
+      - Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array
+      - Stop when all `applyRequires` artifacts are done
+
+   c. **If an artifact requires user input** (unclear context):
+      - Use **AskUserQuestion tool** to clarify
+      - Then continue with creation
+
+5. **Show final status**
+   ```bash
+   openspec status --change "<name>"
+   ```
+
+**Output**
+
+After completing all artifacts, summarize:
+- Change name and location
+- List of artifacts created with brief descriptions
+- What's ready: "All artifacts created! Ready for implementation."
+- Prompt: "Run `/opsx-apply` or ask me to implement to start working on the tasks."
+
+**Artifact Creation Guidelines**
+
+- Follow the `instruction` field from `openspec instructions` for each artifact type
+- The schema defines what each artifact should contain - follow it
+- Read dependency artifacts for context before creating new ones
+- Use `template` as the structure for your output file - fill in its sections
+- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
+  - Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
+  - These guide what you write, but should never appear in the output
+
+**Guardrails**
+- Create ALL artifacts needed for implementation (as defined by schema's `apply.requires`)
+- Always read dependency artifacts before creating a new one
+- If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
+- If a change with that name already exists, ask if user wants to continue it or create a new one
+- Verify each artifact file exists after writing before proceeding to next

AGENTS.md

@@ -73,12 +73,14 @@ sqlx migrate add -r migration_name
 
 ### Docker Development
 
+`docker-compose.yml` est à la **racine** du projet (pas dans `infra/`).
+
 ```bash
 # Start infrastructure only
-cd infra && docker compose up -d postgres meilisearch
+docker compose up -d postgres meilisearch
 
 # Start full stack
-cd infra && docker compose up -d
+docker compose up -d
 
 # View logs
 docker compose logs -f api
@@ -226,24 +228,21 @@ pub struct BookItem {
 ```
 stripstream-librarian/
 ├── apps/
-│   ├── api/           # REST API (axum)
-│   │   └── src/
-│   │       ├── main.rs
-│   │       ├── books.rs
-│   │       ├── pages.rs
-│   │       └── ...
-│   ├── indexer/       # Background indexing service
-│   │   └── src/
-│   │       └── main.rs
-│   └── backoffice/    # Next.js admin UI
+│   ├── api/           # REST API (axum) — port 7080
+│   │   └── src/       # books.rs, pages.rs, thumbnails.rs, state.rs, auth.rs...
+│   ├── indexer/       # Background indexing service — port 7081
+│   │   └── src/       # worker.rs, scanner.rs, batch.rs, scheduler.rs, watcher.rs...
+│   └── backoffice/    # Next.js admin UI — port 7082
 ├── crates/
-│   ├── core/          # Shared config
+│   ├── core/          # Shared config (env vars)
 │   │   └── src/config.rs
 │   └── parsers/       # Book parsing (CBZ, CBR, PDF)
 ├── infra/
-│   ├── migrations/    # SQL migrations
-│   └── docker-compose.yml
-└── libraries/         # Book storage (mounted volume)
+│   └── migrations/    # SQL migrations (sqlx)
+├── data/
+│   └── thumbnails/    # Thumbnails générés par l'API
+├── libraries/         # Book storage (mounted volume)
+└── docker-compose.yml # À la racine (pas dans infra/)
 ```
 
 ### Key Files
@@ -251,8 +250,13 @@ stripstream-librarian/
 | File | Purpose |
 |------|---------|
 | `apps/api/src/books.rs` | Book CRUD endpoints |
-| `apps/api/src/pages.rs` | Page rendering & caching |
-| `apps/indexer/src/main.rs` | Indexing logic, batch processing |
+| `apps/api/src/pages.rs` | Page rendering & caching (LRU + disk) |
+| `apps/api/src/thumbnails.rs` | Endpoints pour créer des jobs thumbnail (rebuild/regenerate) |
+| `apps/api/src/state.rs` | AppState, Semaphore concurrent_renders |
+| `apps/indexer/src/scanner.rs` | Phase 1 discovery : scan rapide sans I/O archive, skip dossiers inchangés |
+| `apps/indexer/src/analyzer.rs` | Phase 2 analysis : `analyze_book` + génération thumbnails WebP |
+| `apps/indexer/src/batch.rs` | Bulk DB ops via UNNEST |
+| `apps/indexer/src/worker.rs` | Job loop, watcher, scheduler orchestration |
 | `crates/parsers/src/lib.rs` | Format detection, metadata parsing |
 | `crates/core/src/config.rs` | Configuration from environment |
 | `infra/migrations/*.sql` | Database schema |
@@ -269,7 +273,7 @@ impl IndexerConfig {
     pub fn from_env() -> Result<Self> {
         Ok(Self {
             listen_addr: std::env::var("INDEXER_LISTEN_ADDR")
-                .unwrap_or_else(|_| "0.0.0.0:8081".to_string()),
+                .unwrap_or_else(|_| "0.0.0.0:7081".to_string()),
             database_url: std::env::var("DATABASE_URL")
                 .context("DATABASE_URL is required")?,
             // ...
@@ -298,4 +302,6 @@ fn remap_libraries_path(path: &str) -> String {
 - **Workspace**: This is a Cargo workspace. Always specify the package when building specific apps.
 - **Dependencies**: External crates are defined in workspace `Cargo.toml`, not individual `Cargo.toml`.
 - **Database**: PostgreSQL is required. Run migrations before starting services.
-- **External Tools**: The indexer relies on `unar` (for CBR) and `pdftoppm` (for PDF) being installed on the system.
+- **External Tools**: 4 system tools required — `unrar` (CBR page count), `unar` (CBR extraction), `pdfinfo` (PDF page count), `pdftoppm` (PDF page render). Note: `unrar` and `unar` are distinct tools.
+- **Thumbnails**: generated by the **indexer** service (phase 2, `analyzer.rs`). The API only creates jobs in DB — it does not generate thumbnails directly.
+- **Sub-AGENTS.md**: module-specific guidelines in `apps/api/`, `apps/indexer/`, `apps/backoffice/`, `crates/parsers/`.

CLAUDE.md

@@ -0,0 +1,72 @@
+# Stripstream Librarian
+
+Gestionnaire de bibliothèque de bandes dessinées/ebooks. Workspace Cargo multi-crates avec backoffice Next.js.
+
+## Architecture
+
+| Service | Dossier | Port local |
+|---------|---------|------------|
+| API REST (axum) | `apps/api/` | 7080 |
+| Indexer (background) | `apps/indexer/` | 7081 |
+| Backoffice (Next.js) | `apps/backoffice/` | 7082 |
+| PostgreSQL | infra | 6432 |
+| Meilisearch | infra | 7700 |
+
+Crates partagés : `crates/core` (config env), `crates/parsers` (CBZ/CBR/PDF).
+
+## Commandes
+
+```bash
+# Build
+cargo build                     # workspace entier
+cargo build -p api              # crate spécifique
+cargo build --release           # version optimisée
+
+# Linting / format
+cargo clippy
+cargo fmt
+
+# Tests
+cargo test
+cargo test -p parsers
+
+# Infra (dépendances uniquement) — docker-compose.yml est à la racine
+docker compose up -d postgres meilisearch
+
+# Backoffice dev
+cd apps/backoffice && npm install && npm run dev  # http://localhost:7082
+
+# Migrations
+sqlx migrate run  # DATABASE_URL doit être défini
+```
+
+## Environnement
+
+```bash
+cp .env.example .env  # puis éditer les valeurs REQUIRED
+```
+
+Variables **requises** au démarrage : `DATABASE_URL`, `MEILI_URL`, `MEILI_MASTER_KEY`, `API_BOOTSTRAP_TOKEN`.
+
+## Gotchas
+
+- **Dépendances système** : 4 outils requis — `unrar` (CBR listing), `unar` (CBR extraction), `pdfinfo` (PDF page count), `pdftoppm` (PDF rendu). `unrar` ≠ `unar`.
+- **Port backoffice** : `npm run dev` écoute sur **7082**, pas 3000.
+- **LIBRARIES_ROOT_PATH** : les chemins en DB commencent par `/libraries/` ; en dev local, définir cette variable pour remapper vers le dossier réel.
+- **Thumbnails** : stockés dans `THUMBNAIL_DIRECTORY` (défaut `/data/thumbnails`), générés par **l'API** (pas l'indexer) — l'indexer déclenche un checkup via `POST /index/jobs/:id/thumbnails/checkup`.
+- **Workspace Cargo** : les dépendances externes sont définies dans le `Cargo.toml` racine, pas dans les crates individuels.
+- **Migrations** : dossier `infra/migrations/`, géré par sqlx. Toujours migrer avant de démarrer les services.
+
+## Fichiers clés
+
+| Fichier | Rôle |
+|---------|------|
+| `crates/core/src/config.rs` | Config depuis env (API, Indexer, AdminUI) |
+| `crates/parsers/src/lib.rs` | Détection format, extraction métadonnées |
+| `apps/api/src/books.rs` | Endpoints CRUD livres |
+| `apps/api/src/pages.rs` | Rendu pages + cache LRU |
+| `apps/indexer/src/scanner.rs` | Scan filesystem |
+| `infra/migrations/*.sql` | Schéma DB |
+
+> Voir `AGENTS.md` pour les conventions de code détaillées (error handling, patterns sqlx, async/tokio).
+> Des `AGENTS.md` spécifiques existent dans `apps/api/`, `apps/indexer/`, `apps/backoffice/`, `crates/parsers/`.

Cargo.lock

@@ -1146,6 +1146,8 @@ dependencies = [
  "anyhow",
  "axum",
  "chrono",
+ "futures",
+ "image",
  "notify",
  "parsers",
  "rand 0.8.5",
@@ -1161,6 +1163,7 @@ dependencies = [
  "tracing-subscriber",
  "uuid",
  "walkdir",
+ "webp",
 ]
 
 [[package]]

Cargo.toml

@@ -33,5 +33,6 @@ tracing = "0.1"
 tracing-subscriber = { version = "0.3", features = ["env-filter", "fmt"] }
 uuid = { version = "1.12", features = ["serde", "v4"] }
 walkdir = "2.5"
+webp = "0.3"
 utoipa = "4.0"
 utoipa-swagger-ui = "6.0"

README.md

@@ -38,16 +38,16 @@ docker compose up -d
 ```
 
 This will start:
-- PostgreSQL (port 5432)
-- Meilisearch (port 7700)  
-- API service (port 8080)
-- Indexer service (port 8081)
-- Backoffice web UI (port 8082)
+- PostgreSQL (port 6432)
+- Meilisearch (port 7700)
+- API service (port 7080)
+- Indexer service (port 7081)
+- Backoffice web UI (port 7082)
 
 ### Accessing the Application
 
-- **Backoffice**: http://localhost:8082
-- **API**: http://localhost:8080
+- **Backoffice**: http://localhost:7082
+- **API**: http://localhost:7080
 - **Meilisearch**: http://localhost:7700
 
 ### Default Credentials
@@ -113,9 +113,9 @@ The backoffice will be available at http://localhost:3000
 
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `API_LISTEN_ADDR` | API service bind address | `0.0.0.0:8080` |
-| `INDEXER_LISTEN_ADDR` | Indexer service bind address | `0.0.0.0:8081` |
-| `BACKOFFICE_PORT` | Backoffice web UI port | `8082` |
+| `API_LISTEN_ADDR` | API service bind address | `0.0.0.0:7080` |
+| `INDEXER_LISTEN_ADDR` | Indexer service bind address | `0.0.0.0:7081` |
+| `BACKOFFICE_PORT` | Backoffice web UI port | `7082` |
 | `DATABASE_URL` | PostgreSQL connection string | `postgres://stripstream:stripstream@postgres:5432/stripstream` |
 | `MEILI_URL` | Meilisearch connection URL | `http://meilisearch:7700` |
 | `MEILI_MASTER_KEY` | Meilisearch master key (required) | - |
@@ -128,7 +128,7 @@ The backoffice will be available at http://localhost:3000
 The API is documented with OpenAPI/Swagger. When running locally, access the docs at:
 
 ```
-http://localhost:8080/api-docs
+http://localhost:7080/swagger-ui
 ```
 
 ## Project Structure

apps/api/AGENTS.md

@@ -0,0 +1,73 @@
+# apps/api — REST API (axum)
+
+Service HTTP sur le port **7080**. Voir `AGENTS.md` racine pour les conventions globales.
+
+## Structure des fichiers
+
+| Fichier | Rôle |
+|---------|------|
+| `main.rs` | Routes, initialisation AppState, Semaphore concurrent_renders |
+| `state.rs` | `AppState` (pool, caches, métriques), `load_concurrent_renders` |
+| `auth.rs` | Middlewares `require_admin` / `require_read`, authentification tokens |
+| `error.rs` | `ApiError` avec constructeurs `bad_request`, `not_found`, `internal`, etc. |
+| `books.rs` | CRUD livres, thumbnails |
+| `pages.rs` | Rendu page + double cache (mémoire LRU + disque) |
+| `libraries.rs` | CRUD bibliothèques, déclenchement scans |
+| `index_jobs.rs` | Suivi jobs, SSE streaming progression |
+| `thumbnails.rs` | Rebuild/regénération thumbnails |
+| `tokens.rs` | Gestion tokens API (create/revoke) |
+| `settings.rs` | Paramètres applicatifs (stockés en DB, clé `limits`) |
+| `openapi.rs` | Doc OpenAPI via utoipa, accessible sur `/swagger-ui` |
+
+## Patterns clés
+
+### Handler type
+```rust
+async fn my_handler(
+    State(state): State<AppState>,
+    Path(id): Path<Uuid>,
+) -> Result<Json<MyDto>, ApiError> {
+    // ...
+}
+```
+
+### Erreurs API
+```rust
+// Constructeurs disponibles dans error.rs
+ApiError::bad_request("message")
+ApiError::not_found("resource not found")
+ApiError::internal("unexpected error")
+ApiError::unauthorized("missing token")
+ApiError::forbidden("admin required")
+
+// Conversion auto depuis sqlx::Error et std::io::Error
+```
+
+### Authentification
+- **Bootstrap token** : comparaison directe (`API_BOOTSTRAP_TOKEN`), scope Admin
+- **Tokens DB** : format `stl_<prefix>_<secret>`, hash argon2 en DB, scope `admin` ou `read`
+- Middleware `require_admin` → routes admin ; `require_read` → routes lecture
+
+### OpenAPI (utoipa)
+```rust
+#[utoipa::path(get, path = "/books/{id}", ...)]
+async fn get_book(...) { }
+// Ajouter le handler dans openapi.rs (ApiDoc)
+```
+
+### Cache pages (`pages.rs`)
+- **Cache mémoire** : LRU 512 entrées (`AppState.page_cache`)
+- **Cache disque** : `IMAGE_CACHE_DIR` (défaut `/tmp/stripstream-image-cache`), clé SHA256
+- Concurrence limitée par `AppState.page_render_limit` (Semaphore, configurable en DB)
+- `spawn_blocking` pour le rendu image (CPU-bound)
+
+### Paramètre concurrent_renders
+Stocké en DB : `SELECT value FROM app_settings WHERE key = 'limits'` → JSON `{"concurrent_renders": N}`.
+Chargé au démarrage dans `load_concurrent_renders`.
+
+## Gotchas
+
+- **LIBRARIES_ROOT_PATH** : les `abs_path` en DB commencent par `/libraries/`. Appeler `remap_libraries_path()` avant tout accès fichier.
+- **Rate limit lecture** : middleware `read_rate_limit` sur les routes read (100 req/5s par défaut).
+- **Métriques** : `/metrics` expose `requests_total`, `page_cache_hits`, `page_cache_misses` (atomics dans `AppState.metrics`).
+- **Swagger** : accessible sur `/swagger-ui`, spec JSON sur `/openapi.json`.

apps/api/Cargo.toml

@@ -31,5 +31,5 @@ uuid.workspace = true
 zip = { version = "2.2", default-features = false, features = ["deflate"] }
 utoipa.workspace = true
 utoipa-swagger-ui = { workspace = true, features = ["axum"] }
-webp = "0.3"
+webp.workspace = true
 walkdir = "2"

apps/api/Dockerfile

@@ -26,5 +26,5 @@ RUN sed -i '/en_US.UTF-8/s/^# //g' /etc/locale.gen && locale-gen
 ENV LANG=en_US.UTF-8
 ENV LC_ALL=en_US.UTF-8
 COPY --from=builder /app/target/release/api /usr/local/bin/api
-EXPOSE 8080
+EXPOSE 7080
 CMD ["/usr/local/bin/api"]

apps/api/src/api_middleware.rs

@@ -0,0 +1,43 @@
+use axum::{
+    extract::State,
+    middleware::Next,
+    response::{IntoResponse, Response},
+};
+use std::time::Duration;
+use std::sync::atomic::Ordering;
+
+use crate::state::AppState;
+
+pub async fn request_counter(
+    State(state): State<AppState>,
+    req: axum::extract::Request,
+    next: Next,
+) -> Response {
+    state.metrics.requests_total.fetch_add(1, Ordering::Relaxed);
+    next.run(req).await
+}
+
+pub async fn read_rate_limit(
+    State(state): State<AppState>,
+    req: axum::extract::Request,
+    next: Next,
+) -> Response {
+    let mut limiter = state.read_rate_limit.lock().await;
+    if limiter.window_started_at.elapsed() >= Duration::from_secs(1) {
+        limiter.window_started_at = std::time::Instant::now();
+        limiter.requests_in_window = 0;
+    }
+
+    let rate_limit = state.settings.read().await.rate_limit_per_second;
+    if limiter.requests_in_window >= rate_limit {
+        return (
+            axum::http::StatusCode::TOO_MANY_REQUESTS,
+            "rate limit exceeded",
+        )
+            .into_response();
+    }
+
+    limiter.requests_in_window += 1;
+    drop(limiter);
+    next.run(req).await
+}

apps/api/src/auth.rs

@@ -8,7 +8,7 @@ use axum::{
 use chrono::Utc;
 use sqlx::Row;
 
-use crate::{error::ApiError, AppState};
+use crate::{error::ApiError, state::AppState};
 
 #[derive(Clone, Debug)]
 pub enum Scope {

apps/api/src/books.rs

@@ -5,7 +5,7 @@ use sqlx::Row;
 use uuid::Uuid;
 use utoipa::ToSchema;
 
-use crate::{error::ApiError, AppState};
+use crate::{error::ApiError, index_jobs::IndexJobResponse, state::AppState};
 
 #[derive(Deserialize, ToSchema)]
 pub struct ListBooksQuery {
@@ -63,6 +63,11 @@ pub struct BookDetails {
     pub file_path: Option<String>,
     pub file_format: Option<String>,
     pub file_parse_status: Option<String>,
+    /// Reading status: "unread", "reading", or "read"
+    pub reading_status: String,
+    pub reading_current_page: Option<i32>,
+    #[schema(value_type = Option<String>)]
+    pub reading_last_read_at: Option<DateTime<Utc>>,
 }
 
 /// List books with optional filtering and pagination
@@ -189,7 +194,10 @@ pub async fn get_book(
     let row = sqlx::query(
         r#"
         SELECT b.id, b.library_id, b.kind, b.title, b.author, b.series, b.volume, b.language, b.page_count, b.thumbnail_path,
-               bf.abs_path, bf.format, bf.parse_status
+               bf.abs_path, bf.format, bf.parse_status,
+               COALESCE(brp.status, 'unread') AS reading_status,
+               brp.current_page AS reading_current_page,
+               brp.last_read_at AS reading_last_read_at
         FROM books b
         LEFT JOIN LATERAL (
           SELECT abs_path, format, parse_status
@@ -198,6 +206,7 @@ pub async fn get_book(
           ORDER BY updated_at DESC
           LIMIT 1
         ) bf ON TRUE
+        LEFT JOIN book_reading_progress brp ON brp.book_id = b.id
         WHERE b.id = $1
         "#,
     )
@@ -221,6 +230,9 @@ pub async fn get_book(
         file_path: row.get("abs_path"),
         file_format: row.get("format"),
         file_parse_status: row.get("parse_status"),
+        reading_status: row.get("reading_status"),
+        reading_current_page: row.get("reading_current_page"),
+        reading_last_read_at: row.get("reading_last_read_at"),
     }))
 }
 
@@ -341,12 +353,134 @@ pub async fn list_series(
     }))
 }
 
+fn remap_libraries_path(path: &str) -> String {
+    if let Ok(root) = std::env::var("LIBRARIES_ROOT_PATH") {
+        if path.starts_with("/libraries/") {
+            return path.replacen("/libraries", &root, 1);
+        }
+    }
+    path.to_string()
+}
+
+fn unmap_libraries_path(path: &str) -> String {
+    if let Ok(root) = std::env::var("LIBRARIES_ROOT_PATH") {
+        if path.starts_with(&root) {
+            return path.replacen(&root, "/libraries", 1);
+        }
+    }
+    path.to_string()
+}
+
+/// Enqueue a CBR → CBZ conversion job for a single book
+#[utoipa::path(
+    post,
+    path = "/books/{id}/convert",
+    tag = "books",
+    params(
+        ("id" = String, Path, description = "Book UUID"),
+    ),
+    responses(
+        (status = 200, body = IndexJobResponse),
+        (status = 404, description = "Book not found"),
+        (status = 409, description = "Book is not CBR, or target CBZ already exists"),
+        (status = 401, description = "Unauthorized"),
+        (status = 403, description = "Forbidden - Admin scope required"),
+    ),
+    security(("Bearer" = []))
+)]
+pub async fn convert_book(
+    State(state): State<AppState>,
+    Path(book_id): Path<Uuid>,
+) -> Result<Json<IndexJobResponse>, ApiError> {
+    // Fetch book file info
+    let row = sqlx::query(
+        r#"
+        SELECT b.id, bf.abs_path, bf.format
+        FROM books b
+        LEFT JOIN LATERAL (
+            SELECT abs_path, format
+            FROM book_files
+            WHERE book_id = b.id
+            ORDER BY updated_at DESC
+            LIMIT 1
+        ) bf ON TRUE
+        WHERE b.id = $1
+        "#,
+    )
+    .bind(book_id)
+    .fetch_optional(&state.pool)
+    .await?;
+
+    let row = row.ok_or_else(|| ApiError::not_found("book not found"))?;
+    let abs_path: Option<String> = row.get("abs_path");
+    let format: Option<String> = row.get("format");
+
+    if format.as_deref() != Some("cbr") {
+        return Err(ApiError {
+            status: axum::http::StatusCode::CONFLICT,
+            message: "book is not in CBR format".to_string(),
+        });
+    }
+
+    let abs_path = abs_path.ok_or_else(|| ApiError::not_found("book file path not found"))?;
+
+    // Check for existing CBZ with same stem
+    let physical_path = remap_libraries_path(&abs_path);
+    let cbr_path = std::path::Path::new(&physical_path);
+    if let (Some(parent), Some(stem)) = (cbr_path.parent(), cbr_path.file_stem()) {
+        let cbz_path = parent.join(format!("{}.cbz", stem.to_string_lossy()));
+        if cbz_path.exists() {
+            return Err(ApiError {
+                status: axum::http::StatusCode::CONFLICT,
+                message: format!(
+                    "CBZ file already exists: {}",
+                    unmap_libraries_path(&cbz_path.to_string_lossy())
+                ),
+            });
+        }
+    }
+
+    // Create the conversion job
+    let job_id = Uuid::new_v4();
+    sqlx::query(
+        "INSERT INTO index_jobs (id, book_id, type, status) VALUES ($1, $2, 'cbr_to_cbz', 'pending')",
+    )
+    .bind(job_id)
+    .bind(book_id)
+    .execute(&state.pool)
+    .await?;
+
+    let job_row = sqlx::query(
+        "SELECT id, library_id, book_id, type, status, started_at, finished_at, stats_json, error_opt, created_at, progress_percent, processed_files, total_files FROM index_jobs WHERE id = $1",
+    )
+    .bind(job_id)
+    .fetch_one(&state.pool)
+    .await?;
+
+    Ok(Json(crate::index_jobs::map_row(job_row)))
+}
+
 use axum::{
     body::Body,
     http::{header, HeaderMap, HeaderValue, StatusCode},
     response::IntoResponse,
 };
 
+/// Get book thumbnail image
+#[utoipa::path(
+    get,
+    path = "/books/{id}/thumbnail",
+    tag = "books",
+    params(
+        ("id" = String, Path, description = "Book UUID"),
+    ),
+    responses(
+        (status = 200, description = "WebP thumbnail image", content_type = "image/webp"),
+        (status = 404, description = "Book not found or thumbnail not available"),
+        (status = 401, description = "Unauthorized"),
+    ),
+    security(("Bearer" = []))
+)]
 pub async fn get_thumbnail(
     State(state): State<AppState>,
     Path(book_id): Path<Uuid>,

apps/api/src/error.rs

@@ -38,6 +38,13 @@ impl ApiError {
         }
     }
 
+    pub fn unprocessable_entity(message: impl Into<String>) -> Self {
+        Self {
+            status: StatusCode::UNPROCESSABLE_ENTITY,
+            message: message.into(),
+        }
+    }
+
     pub fn not_found(message: impl Into<String>) -> Self {
         Self {
             status: StatusCode::NOT_FOUND,

apps/api/src/handlers.rs

@@ -0,0 +1,26 @@
+use axum::{extract::State, Json};
+use std::sync::atomic::Ordering;
+
+use crate::{error::ApiError, state::AppState};
+
+pub async fn health() -> &'static str {
+    "ok"
+}
+
+pub async fn docs_redirect() -> impl axum::response::IntoResponse {
+    axum::response::Redirect::to("/swagger-ui/")
+}
+
+pub async fn ready(State(state): State<AppState>) -> Result<Json<serde_json::Value>, ApiError> {
+    sqlx::query("SELECT 1").execute(&state.pool).await?;
+    Ok(Json(serde_json::json!({"status": "ready"})))
+}
+
+pub async fn metrics(State(state): State<AppState>) -> String {
+    format!(
+        "requests_total {}\npage_cache_hits {}\npage_cache_misses {}\n",
+        state.metrics.requests_total.load(Ordering::Relaxed),
+        state.metrics.page_cache_hits.load(Ordering::Relaxed),
+        state.metrics.page_cache_misses.load(Ordering::Relaxed),
+    )
+}

apps/api/src/index_jobs.rs

@@ -8,7 +8,7 @@ use tokio_stream::Stream;
 use uuid::Uuid;
 use utoipa::ToSchema;
 
-use crate::{error::ApiError, AppState};
+use crate::{error::ApiError, state::AppState};
 
 #[derive(Deserialize, ToSchema)]
 pub struct RebuildRequest {
@@ -24,6 +24,8 @@ pub struct IndexJobResponse {
     pub id: Uuid,
     #[schema(value_type = Option<String>)]
     pub library_id: Option<Uuid>,
+    #[schema(value_type = Option<String>)]
+    pub book_id: Option<Uuid>,
     pub r#type: String,
     pub status: String,
     #[schema(value_type = Option<String>)]
@@ -53,12 +55,16 @@ pub struct IndexJobDetailResponse {
     pub id: Uuid,
     #[schema(value_type = Option<String>)]
     pub library_id: Option<Uuid>,
+    #[schema(value_type = Option<String>)]
+    pub book_id: Option<Uuid>,
     pub r#type: String,
     pub status: String,
     #[schema(value_type = Option<String>)]
     pub started_at: Option<DateTime<Utc>>,
     #[schema(value_type = Option<String>)]
     pub finished_at: Option<DateTime<Utc>>,
+    #[schema(value_type = Option<String>)]
+    pub phase2_started_at: Option<DateTime<Utc>>,
     pub stats_json: Option<serde_json::Value>,
     pub error_opt: Option<String>,
     #[schema(value_type = String)]
@@ -122,7 +128,7 @@ pub async fn enqueue_rebuild(
     .await?;
 
     let row = sqlx::query(
-        "SELECT id, library_id, type, status, started_at, finished_at, stats_json, error_opt, created_at FROM index_jobs WHERE id = $1",
+        "SELECT id, library_id, book_id, type, status, started_at, finished_at, stats_json, error_opt, created_at FROM index_jobs WHERE id = $1",
     )
     .bind(id)
     .fetch_one(&state.pool)
@@ -145,7 +151,7 @@ pub async fn enqueue_rebuild(
 )]
 pub async fn list_index_jobs(State(state): State<AppState>) -> Result<Json<Vec<IndexJobResponse>>, ApiError> {
     let rows = sqlx::query(
-        "SELECT id, library_id, type, status, started_at, finished_at, stats_json, error_opt, created_at, progress_percent, processed_files, total_files FROM index_jobs ORDER BY created_at DESC LIMIT 100",
+        "SELECT id, library_id, book_id, type, status, started_at, finished_at, stats_json, error_opt, created_at, progress_percent, processed_files, total_files FROM index_jobs ORDER BY created_at DESC LIMIT 100",
     )
     .fetch_all(&state.pool)
     .await?;
@@ -185,7 +191,7 @@ pub async fn cancel_job(
     }
 
     let row = sqlx::query(
-        "SELECT id, library_id, type, status, started_at, finished_at, stats_json, error_opt, created_at, progress_percent, processed_files, total_files FROM index_jobs WHERE id = $1",
+        "SELECT id, library_id, book_id, type, status, started_at, finished_at, stats_json, error_opt, created_at, progress_percent, processed_files, total_files FROM index_jobs WHERE id = $1",
     )
     .bind(id.0)
     .fetch_one(&state.pool)
@@ -247,7 +253,7 @@ pub async fn list_folders(
     }
     
     let mut folders = Vec::new();
-    let depth = if params.get("path").is_some() {
+    let depth = if params.contains_key("path") {
         canonical_target.strip_prefix(&canonical_base)
             .map(|p| p.components().count())
             .unwrap_or(0)
@@ -294,6 +300,7 @@ pub fn map_row(row: sqlx::postgres::PgRow) -> IndexJobResponse {
     IndexJobResponse {
         id: row.get("id"),
         library_id: row.get("library_id"),
+        book_id: row.try_get("book_id").ok().flatten(),
         r#type: row.get("type"),
         status: row.get("status"),
         started_at: row.get("started_at"),
@@ -311,10 +318,12 @@ fn map_row_detail(row: sqlx::postgres::PgRow) -> IndexJobDetailResponse {
     IndexJobDetailResponse {
         id: row.get("id"),
         library_id: row.get("library_id"),
+        book_id: row.try_get("book_id").ok().flatten(),
         r#type: row.get("type"),
         status: row.get("status"),
         started_at: row.get("started_at"),
         finished_at: row.get("finished_at"),
+        phase2_started_at: row.try_get("phase2_started_at").ok().flatten(),
         stats_json: row.get("stats_json"),
         error_opt: row.get("error_opt"),
         created_at: row.get("created_at"),
@@ -339,9 +348,9 @@ fn map_row_detail(row: sqlx::postgres::PgRow) -> IndexJobDetailResponse {
 )]
 pub async fn get_active_jobs(State(state): State<AppState>) -> Result<Json<Vec<IndexJobResponse>>, ApiError> {
     let rows = sqlx::query(
-        "SELECT id, library_id, type, status, started_at, finished_at, stats_json, error_opt, created_at, progress_percent, processed_files, total_files
-         FROM index_jobs 
-         WHERE status IN ('pending', 'running', 'generating_thumbnails') 
+        "SELECT id, library_id, book_id, type, status, started_at, finished_at, stats_json, error_opt, created_at, progress_percent, processed_files, total_files
+         FROM index_jobs
+         WHERE status IN ('pending', 'running', 'generating_thumbnails')
          ORDER BY created_at ASC"
     )
     .fetch_all(&state.pool)
@@ -371,8 +380,8 @@ pub async fn get_job_details(
     id: axum::extract::Path<Uuid>,
 ) -> Result<Json<IndexJobDetailResponse>, ApiError> {
     let row = sqlx::query(
-        "SELECT id, library_id, type, status, started_at, finished_at, stats_json, error_opt, created_at,
-                current_file, progress_percent, total_files, processed_files
+        "SELECT id, library_id, book_id, type, status, started_at, finished_at, phase2_started_at,
+                stats_json, error_opt, created_at, current_file, progress_percent, total_files, processed_files
          FROM index_jobs WHERE id = $1"
     )
     .bind(id.0)

apps/api/src/libraries.rs

@@ -6,7 +6,7 @@ use sqlx::Row;
 use uuid::Uuid;
 use utoipa::ToSchema;
 
-use crate::{error::ApiError, AppState};
+use crate::{error::ApiError, state::AppState};
 
 #[derive(Serialize, ToSchema)]
 pub struct LibraryResponse {
@@ -18,6 +18,7 @@ pub struct LibraryResponse {
     pub book_count: i64,
     pub monitor_enabled: bool,
     pub scan_mode: String,
+    #[schema(value_type = Option<String>)]
     pub next_scan_at: Option<chrono::DateTime<chrono::Utc>>,
     pub watcher_enabled: bool,
 }

apps/api/src/main.rs

@@ -1,70 +1,37 @@
 mod auth;
 mod books;
 mod error;
+mod handlers;
 mod index_jobs;
 mod libraries;
+mod api_middleware;
 mod openapi;
 mod pages;
+mod reading_progress;
 mod search;
 mod settings;
+mod state;
 mod thumbnails;
 mod tokens;
 
-use std::{
-    num::NonZeroUsize,
-    sync::{
-        atomic::{AtomicU64, Ordering},
-        Arc,
-    },
-    time::{Duration, Instant},
-};
+use std::sync::Arc;
+use std::time::Instant;
 
 use axum::{
     middleware,
-    response::IntoResponse,
     routing::{delete, get},
-    Json, Router,
+    Router,
 };
 use utoipa::OpenApi;
 use utoipa_swagger_ui::SwaggerUi;
 use lru::LruCache;
+use std::num::NonZeroUsize;
 use stripstream_core::config::ApiConfig;
 use sqlx::postgres::PgPoolOptions;
-use tokio::sync::{Mutex, Semaphore};
+use tokio::sync::{Mutex, RwLock, Semaphore};
 use tracing::info;
 
-#[derive(Clone)]
-struct AppState {
-    pool: sqlx::PgPool,
-    bootstrap_token: Arc<str>,
-    meili_url: Arc<str>,
-    meili_master_key: Arc<str>,
-    page_cache: Arc<Mutex<LruCache<String, Arc<Vec<u8>>>>>,
-    page_render_limit: Arc<Semaphore>,
-    metrics: Arc<Metrics>,
-    read_rate_limit: Arc<Mutex<ReadRateLimit>>,
-}
-
-struct Metrics {
-    requests_total: AtomicU64,
-    page_cache_hits: AtomicU64,
-    page_cache_misses: AtomicU64,
-}
-
-struct ReadRateLimit {
-    window_started_at: Instant,
-    requests_in_window: u32,
-}
-
-impl Metrics {
-    fn new() -> Self {
-        Self {
-            requests_total: AtomicU64::new(0),
-            page_cache_hits: AtomicU64::new(0),
-            page_cache_misses: AtomicU64::new(0),
-        }
-    }
-}
+use crate::state::{load_concurrent_renders, load_dynamic_settings, AppState, Metrics, ReadRateLimit};
 
 #[tokio::main]
 async fn main() -> anyhow::Result<()> {
@@ -80,18 +47,35 @@ async fn main() -> anyhow::Result<()> {
         .connect(&config.database_url)
         .await?;
 
+    // Load concurrent_renders from settings, default to 8
+    let concurrent_renders = load_concurrent_renders(&pool).await;
+    info!("Using concurrent_renders limit: {}", concurrent_renders);
+
+    let dynamic_settings = load_dynamic_settings(&pool).await;
+    info!(
+        "Dynamic settings: rate_limit={}, timeout={}s, format={}, quality={}, filter={}, max_width={}, cache_dir={}",
+        dynamic_settings.rate_limit_per_second,
+        dynamic_settings.timeout_seconds,
+        dynamic_settings.image_format,
+        dynamic_settings.image_quality,
+        dynamic_settings.image_filter,
+        dynamic_settings.image_max_width,
+        dynamic_settings.cache_directory,
+    );
+
     let state = AppState {
         pool,
         bootstrap_token: Arc::from(config.api_bootstrap_token),
         meili_url: Arc::from(config.meili_url),
         meili_master_key: Arc::from(config.meili_master_key),
         page_cache: Arc::new(Mutex::new(LruCache::new(NonZeroUsize::new(512).expect("non-zero")))),
-        page_render_limit: Arc::new(Semaphore::new(8)),
+        page_render_limit: Arc::new(Semaphore::new(concurrent_renders)),
         metrics: Arc::new(Metrics::new()),
         read_rate_limit: Arc::new(Mutex::new(ReadRateLimit {
             window_started_at: Instant::now(),
             requests_in_window: 0,
         })),
+        settings: Arc::new(RwLock::new(dynamic_settings)),
     };
 
     let admin_routes = Router::new()
@@ -99,6 +83,7 @@ async fn main() -> anyhow::Result<()> {
         .route("/libraries/:id", delete(libraries::delete_library))
         .route("/libraries/:id/scan", axum::routing::post(libraries::scan_library))
         .route("/libraries/:id/monitoring", axum::routing::patch(libraries::update_monitoring))
+        .route("/books/:id/convert", axum::routing::post(books::convert_book))
         .route("/index/rebuild", axum::routing::post(index_jobs::enqueue_rebuild))
         .route("/index/thumbnails/rebuild", axum::routing::post(thumbnails::start_thumbnails_rebuild))
         .route("/index/thumbnails/regenerate", axum::routing::post(thumbnails::start_thumbnails_regenerate))
@@ -106,7 +91,6 @@ async fn main() -> anyhow::Result<()> {
         .route("/index/jobs/active", get(index_jobs::get_active_jobs))
         .route("/index/jobs/:id", get(index_jobs::get_job_details))
         .route("/index/jobs/:id/stream", get(index_jobs::stream_job_progress))
-        .route("/index/jobs/:id/thumbnails/checkup", axum::routing::post(thumbnails::start_checkup))
         .route("/index/jobs/:id/errors", get(index_jobs::get_job_errors))
         .route("/index/cancel/:id", axum::routing::post(index_jobs::cancel_job))
         .route("/folders", get(index_jobs::list_folders))
@@ -123,23 +107,24 @@ async fn main() -> anyhow::Result<()> {
         .route("/books/:id", get(books::get_book))
         .route("/books/:id/thumbnail", get(books::get_thumbnail))
         .route("/books/:id/pages/:n", get(pages::get_page))
+        .route("/books/:id/progress", get(reading_progress::get_reading_progress).patch(reading_progress::update_reading_progress))
         .route("/libraries/:library_id/series", get(books::list_series))
         .route("/search", get(search::search_books))
-        .route_layer(middleware::from_fn_with_state(state.clone(), read_rate_limit))
+        .route_layer(middleware::from_fn_with_state(state.clone(), api_middleware::read_rate_limit))
         .route_layer(middleware::from_fn_with_state(
             state.clone(),
             auth::require_read,
         ));
 
     let app = Router::new()
-        .route("/health", get(health))
-        .route("/ready", get(ready))
-        .route("/metrics", get(metrics))
-        .route("/docs", get(docs_redirect))
+        .route("/health", get(handlers::health))
+        .route("/ready", get(handlers::ready))
+        .route("/metrics", get(handlers::metrics))
+        .route("/docs", get(handlers::docs_redirect))
         .merge(SwaggerUi::new("/swagger-ui").url("/openapi.json", openapi::ApiDoc::openapi()))
         .merge(admin_routes)
         .merge(read_routes)
-        .layer(middleware::from_fn_with_state(state.clone(), request_counter))
+        .layer(middleware::from_fn_with_state(state.clone(), api_middleware::request_counter))
         .with_state(state);
 
     let listener = tokio::net::TcpListener::bind(&config.listen_addr).await?;
@@ -148,57 +133,3 @@ async fn main() -> anyhow::Result<()> {
     Ok(())
 }
 
-async fn health() -> &'static str {
-    "ok"
-}
-
-async fn docs_redirect() -> impl axum::response::IntoResponse {
-    axum::response::Redirect::to("/swagger-ui/")
-}
-
-async fn ready(axum::extract::State(state): axum::extract::State<AppState>) -> Result<Json<serde_json::Value>, error::ApiError> {
-    sqlx::query("SELECT 1").execute(&state.pool).await?;
-    Ok(Json(serde_json::json!({"status": "ready"})))
-}
-
-async fn metrics(axum::extract::State(state): axum::extract::State<AppState>) -> String {
-    format!(
-        "requests_total {}\npage_cache_hits {}\npage_cache_misses {}\n",
-        state.metrics.requests_total.load(Ordering::Relaxed),
-        state.metrics.page_cache_hits.load(Ordering::Relaxed),
-        state.metrics.page_cache_misses.load(Ordering::Relaxed),
-    )
-}
-
-async fn request_counter(
-    axum::extract::State(state): axum::extract::State<AppState>,
-    req: axum::extract::Request,
-    next: axum::middleware::Next,
-) -> axum::response::Response {
-    state.metrics.requests_total.fetch_add(1, Ordering::Relaxed);
-    next.run(req).await
-}
-
-async fn read_rate_limit(
-    axum::extract::State(state): axum::extract::State<AppState>,
-    req: axum::extract::Request,
-    next: axum::middleware::Next,
-) -> axum::response::Response {
-    let mut limiter = state.read_rate_limit.lock().await;
-    if limiter.window_started_at.elapsed() >= Duration::from_secs(1) {
-        limiter.window_started_at = Instant::now();
-        limiter.requests_in_window = 0;
-    }
-
-    if limiter.requests_in_window >= 120 {
-        return (
-            axum::http::StatusCode::TOO_MANY_REQUESTS,
-            "rate limit exceeded",
-        )
-            .into_response();
-    }
-
-    limiter.requests_in_window += 1;
-    drop(limiter);
-    next.run(req).await
-}

apps/api/src/openapi.rs

@@ -6,7 +6,11 @@ use utoipa::OpenApi;
     paths(
         crate::books::list_books,
         crate::books::get_book,
+        crate::reading_progress::get_reading_progress,
+        crate::reading_progress::update_reading_progress,
+        crate::books::get_thumbnail,
         crate::books::list_series,
+        crate::books::convert_book,
         crate::pages::get_page,
         crate::search::search_books,
         crate::index_jobs::enqueue_rebuild,
@@ -27,6 +31,12 @@ use utoipa::OpenApi;
         crate::tokens::list_tokens,
         crate::tokens::create_token,
         crate::tokens::revoke_token,
+        crate::settings::get_settings,
+        crate::settings::get_setting,
+        crate::settings::update_setting,
+        crate::settings::clear_cache,
+        crate::settings::get_cache_stats,
+        crate::settings::get_thumbnail_stats,
     ),
     components(
         schemas(
@@ -34,7 +44,10 @@ use utoipa::OpenApi;
             crate::books::BookItem,
             crate::books::BooksPage,
             crate::books::BookDetails,
+            crate::reading_progress::ReadingProgressResponse,
+            crate::reading_progress::UpdateReadingProgressRequest,
             crate::books::SeriesItem,
+            crate::books::SeriesPage,
             crate::pages::PageQuery,
             crate::search::SearchQuery,
             crate::search::SearchResponse,
@@ -51,6 +64,10 @@ use utoipa::OpenApi;
             crate::tokens::CreateTokenRequest,
             crate::tokens::TokenResponse,
             crate::tokens::CreatedTokenResponse,
+            crate::settings::UpdateSettingRequest,
+            crate::settings::ClearCacheResponse,
+            crate::settings::CacheStats,
+            crate::settings::ThumbnailStats,
             ErrorResponse,
         )
     ),
@@ -59,9 +76,11 @@ use utoipa::OpenApi;
     ),
     tags(
         (name = "books", description = "Read-only endpoints for browsing and searching books"),
+        (name = "reading-progress", description = "Reading progress tracking per book"),
         (name = "libraries", description = "Library management endpoints (Admin only)"),
         (name = "indexing", description = "Search index management and job control (Admin only)"),
         (name = "tokens", description = "API token management (Admin only)"),
+        (name = "settings", description = "Application settings and cache management (Admin only)"),
     ),
     modifiers(&SecurityAddon)
 )]
@@ -106,15 +125,24 @@ mod tests {
             .to_pretty_json()
             .expect("Failed to serialize OpenAPI");
 
-        // Check that there are no references to non-existent schemas
-        assert!(
-            !json.contains("\"/components/schemas/Uuid\""),
-            "Uuid schema should not be referenced"
-        );
-        assert!(
-            !json.contains("\"/components/schemas/DateTime\""),
-            "DateTime schema should not be referenced"
-        );
+        // Check that all $ref targets exist in components/schemas
+        let doc: serde_json::Value =
+            serde_json::from_str(&json).expect("OpenAPI JSON should be valid");
+        let empty = serde_json::Map::new();
+        let schemas = doc["components"]["schemas"]
+            .as_object()
+            .unwrap_or(&empty);
+        let prefix = "#/components/schemas/";
+        let mut broken: Vec<String> = Vec::new();
+        for part in json.split(prefix).skip(1) {
+            if let Some(name) = part.split('"').next() {
+                if !schemas.contains_key(name) {
+                    broken.push(name.to_string());
+                }
+            }
+        }
+        broken.dedup();
+        assert!(broken.is_empty(), "Unresolved schema refs: {:?}", broken);
 
         // Save to file for inspection
         std::fs::write("/tmp/openapi.json", &json).expect("Failed to write file");

apps/api/src/pages.rs

@@ -20,7 +20,7 @@ use tracing::{debug, error, info, instrument, warn};
 use uuid::Uuid;
 use walkdir::WalkDir;
 
-use crate::{error::ApiError, AppState};
+use crate::{error::ApiError, state::AppState};
 
 fn remap_libraries_path(path: &str) -> String {
     if let Ok(root) = std::env::var("LIBRARIES_ROOT_PATH") {
@@ -31,10 +31,12 @@ fn remap_libraries_path(path: &str) -> String {
     path.to_string()
 }
 
-fn get_image_cache_dir() -> PathBuf {
-    std::env::var("IMAGE_CACHE_DIR")
-        .map(PathBuf::from)
-        .unwrap_or_else(|_| PathBuf::from("/tmp/stripstream-image-cache"))
+fn parse_filter(s: &str) -> image::imageops::FilterType {
+    match s {
+        "triangle" => image::imageops::FilterType::Triangle,
+        "nearest" => image::imageops::FilterType::Nearest,
+        _ => image::imageops::FilterType::Lanczos3,
+    }
 }
 
 fn get_cache_key(abs_path: &str, page: u32, format: &str, quality: u8, width: u32) -> String {
@@ -47,8 +49,7 @@ fn get_cache_key(abs_path: &str, page: u32, format: &str, quality: u8, width: u3
     format!("{:x}", hasher.finalize())
 }
 
-fn get_cache_path(cache_key: &str, format: &OutputFormat) -> PathBuf {
-    let cache_dir = get_image_cache_dir();
+fn get_cache_path(cache_key: &str, format: &OutputFormat, cache_dir: &Path) -> PathBuf {
     let prefix = &cache_key[..2];
     let ext = format.extension();
     cache_dir.join(prefix).join(format!("{}.{}", cache_key, ext))
@@ -145,13 +146,21 @@ pub async fn get_page(
         return Err(ApiError::bad_request("page index starts at 1"));
     }
 
-    let format = OutputFormat::parse(query.format.as_deref())?;
-    let quality = query.quality.unwrap_or(80).clamp(1, 100);
+    let (default_format, default_quality, max_width, filter_str, timeout_secs, cache_dir) = {
+        let s = state.settings.read().await;
+        (s.image_format.clone(), s.image_quality, s.image_max_width, s.image_filter.clone(), s.timeout_seconds, s.cache_directory.clone())
+    };
+
+    let format_str = query.format.as_deref().unwrap_or(default_format.as_str());
+    let format = OutputFormat::parse(Some(format_str))?;
+    let quality = query.quality.unwrap_or(default_quality).clamp(1, 100);
     let width = query.width.unwrap_or(0);
-    if width > 2160 {
+    if width > max_width {
         warn!("Invalid width: {}", width);
-        return Err(ApiError::bad_request("width must be <= 2160"));
+        return Err(ApiError::bad_request(format!("width must be <= {}", max_width)));
     }
+    let filter = parse_filter(&filter_str);
+    let cache_dir_path = std::path::PathBuf::from(&cache_dir);
 
     let memory_cache_key = format!("{book_id}:{n}:{}:{quality}:{width}", format.extension());
     
@@ -195,7 +204,7 @@ pub async fn get_page(
     info!("Processing book file: {} (format: {})", abs_path, input_format);
 
     let disk_cache_key = get_cache_key(&abs_path, n, format.extension(), quality, width);
-    let cache_path = get_cache_path(&disk_cache_key, &format);
+    let cache_path = get_cache_path(&disk_cache_key, &format, &cache_dir_path);
     
     if let Some(cached_bytes) = read_from_disk_cache(&cache_path) {
         info!("Disk cache hit for: {}", cache_path.display());
@@ -221,9 +230,9 @@ pub async fn get_page(
     let start_time = std::time::Instant::now();
     
     let bytes = tokio::time::timeout(
-        Duration::from_secs(60),
+        Duration::from_secs(timeout_secs),
         tokio::task::spawn_blocking(move || {
-            render_page(&abs_path_clone, &input_format, n, &format_clone, quality, width)
+            render_page(&abs_path_clone, &input_format, n, &format_clone, quality, width, filter)
         }),
     )
     .await
@@ -306,9 +315,15 @@ pub async fn render_book_page_1(
         .await
         .map_err(|_| ApiError::internal("render limiter unavailable"))?;
 
+    let (timeout_secs, filter_str) = {
+        let s = state.settings.read().await;
+        (s.timeout_seconds, s.image_filter.clone())
+    };
+    let filter = parse_filter(&filter_str);
+
     let abs_path_clone = abs_path.clone();
     let bytes = tokio::time::timeout(
-        Duration::from_secs(60),
+        Duration::from_secs(timeout_secs),
         tokio::task::spawn_blocking(move || {
             render_page(
                 &abs_path_clone,
@@ -317,6 +332,7 @@ pub async fn render_book_page_1(
                 &OutputFormat::Webp,
                 quality,
                 width,
+                filter,
             )
         }),
     )
@@ -334,6 +350,7 @@ fn render_page(
     out_format: &OutputFormat,
     quality: u8,
     width: u32,
+    filter: image::imageops::FilterType,
 ) -> Result<Vec<u8>, ApiError> {
     let page_bytes = match input_format {
         "cbz" => extract_cbz_page(abs_path, page_number)?,
@@ -342,7 +359,7 @@ fn render_page(
         _ => return Err(ApiError::bad_request("unsupported source format")),
     };
 
-    transcode_image(&page_bytes, out_format, quality, width)
+    transcode_image(&page_bytes, out_format, quality, width, filter)
 }
 
 fn extract_cbz_page(abs_path: &str, page_number: u32) -> Result<Vec<u8>, ApiError> {
@@ -495,12 +512,12 @@ fn render_pdf_page(abs_path: &str, page_number: u32, width: u32) -> Result<Vec<u
     Ok(bytes)
 }
 
-fn transcode_image(input: &[u8], out_format: &OutputFormat, quality: u8, width: u32) -> Result<Vec<u8>, ApiError> {
+fn transcode_image(input: &[u8], out_format: &OutputFormat, quality: u8, width: u32, filter: image::imageops::FilterType) -> Result<Vec<u8>, ApiError> {
     debug!("Transcoding image: {} bytes, format: {:?}, quality: {}, width: {}", input.len(), out_format, quality, width);
     let source_format = image::guess_format(input).ok();
     debug!("Source format detected: {:?}", source_format);
     let needs_transcode = source_format.map(|f| !format_matches(&f, out_format)).unwrap_or(true);
-    
+
     if width == 0 && !needs_transcode {
         debug!("No transcoding needed, returning original");
         return Ok(input.to_vec());
@@ -511,10 +528,10 @@ fn transcode_image(input: &[u8], out_format: &OutputFormat, quality: u8, width:
         error!("Failed to load image from memory: {} (input size: {} bytes)", e, input.len());
         ApiError::internal(format!("invalid source image: {e}"))
     })?;
-    
+
     if width > 0 {
         debug!("Resizing image to width: {}", width);
-        image = image.resize(width, u32::MAX, image::imageops::FilterType::Lanczos3);
+        image = image.resize(width, u32::MAX, filter);
     }
 
     debug!("Converting to RGBA...");
@@ -550,12 +567,12 @@ fn transcode_image(input: &[u8], out_format: &OutputFormat, quality: u8, width:
 }
 
 fn format_matches(source: &ImageFormat, target: &OutputFormat) -> bool {
-    match (source, target) {
-        (ImageFormat::Jpeg, OutputFormat::Jpeg) => true,
-        (ImageFormat::Png, OutputFormat::Png) => true,
-        (ImageFormat::WebP, OutputFormat::Webp) => true,
-        _ => false,
-    }
+    matches!(
+        (source, target),
+        (ImageFormat::Jpeg, OutputFormat::Jpeg)
+            | (ImageFormat::Png, OutputFormat::Png)
+            | (ImageFormat::WebP, OutputFormat::Webp)
+    )
 }
 
 fn is_image_name(name: &str) -> bool {

apps/api/src/reading_progress.rs

@@ -0,0 +1,167 @@
+use axum::{extract::{Path, State}, Json};
+use chrono::{DateTime, Utc};
+use serde::{Deserialize, Serialize};
+use sqlx::Row;
+use uuid::Uuid;
+use utoipa::ToSchema;
+
+use crate::{error::ApiError, state::AppState};
+
+#[derive(Serialize, ToSchema)]
+pub struct ReadingProgressResponse {
+    /// Reading status: "unread", "reading", or "read"
+    pub status: String,
+    /// Current page (only set when status is "reading")
+    pub current_page: Option<i32>,
+    #[schema(value_type = Option<String>)]
+    pub last_read_at: Option<DateTime<Utc>>,
+}
+
+#[derive(Deserialize, ToSchema)]
+pub struct UpdateReadingProgressRequest {
+    /// Reading status: "unread", "reading", or "read"
+    pub status: String,
+    /// Required when status is "reading", must be > 0
+    pub current_page: Option<i32>,
+}
+
+/// Get reading progress for a book
+#[utoipa::path(
+    get,
+    path = "/books/{id}/progress",
+    tag = "reading-progress",
+    params(
+        ("id" = String, Path, description = "Book UUID"),
+    ),
+    responses(
+        (status = 200, body = ReadingProgressResponse),
+        (status = 404, description = "Book not found"),
+        (status = 401, description = "Unauthorized"),
+    ),
+    security(("Bearer" = []))
+)]
+pub async fn get_reading_progress(
+    State(state): State<AppState>,
+    Path(id): Path<Uuid>,
+) -> Result<Json<ReadingProgressResponse>, ApiError> {
+    // Verify book exists
+    let exists: bool = sqlx::query_scalar("SELECT EXISTS(SELECT 1 FROM books WHERE id = $1)")
+        .bind(id)
+        .fetch_one(&state.pool)
+        .await?;
+
+    if !exists {
+        return Err(ApiError::not_found("book not found"));
+    }
+
+    let row = sqlx::query(
+        "SELECT status, current_page, last_read_at FROM book_reading_progress WHERE book_id = $1",
+    )
+    .bind(id)
+    .fetch_optional(&state.pool)
+    .await?;
+
+    let response = match row {
+        Some(r) => ReadingProgressResponse {
+            status: r.get("status"),
+            current_page: r.get("current_page"),
+            last_read_at: r.get("last_read_at"),
+        },
+        None => ReadingProgressResponse {
+            status: "unread".to_string(),
+            current_page: None,
+            last_read_at: None,
+        },
+    };
+
+    Ok(Json(response))
+}
+
+/// Update reading progress for a book
+#[utoipa::path(
+    patch,
+    path = "/books/{id}/progress",
+    tag = "reading-progress",
+    params(
+        ("id" = String, Path, description = "Book UUID"),
+    ),
+    request_body = UpdateReadingProgressRequest,
+    responses(
+        (status = 200, body = ReadingProgressResponse),
+        (status = 404, description = "Book not found"),
+        (status = 422, description = "Validation error (missing or invalid current_page for status 'reading')"),
+        (status = 401, description = "Unauthorized"),
+    ),
+    security(("Bearer" = []))
+)]
+pub async fn update_reading_progress(
+    State(state): State<AppState>,
+    Path(id): Path<Uuid>,
+    Json(body): Json<UpdateReadingProgressRequest>,
+) -> Result<Json<ReadingProgressResponse>, ApiError> {
+    // Validate status value
+    if !["unread", "reading", "read"].contains(&body.status.as_str()) {
+        return Err(ApiError::bad_request(format!(
+            "invalid status '{}': must be one of unread, reading, read",
+            body.status
+        )));
+    }
+
+    // Validate current_page for "reading" status
+    if body.status == "reading" {
+        match body.current_page {
+            None => {
+                return Err(ApiError::unprocessable_entity(
+                    "current_page is required when status is 'reading'",
+                ))
+            }
+            Some(p) if p <= 0 => {
+                return Err(ApiError::unprocessable_entity(
+                    "current_page must be greater than 0",
+                ))
+            }
+            _ => {}
+        }
+    }
+
+    // Verify book exists
+    let exists: bool = sqlx::query_scalar("SELECT EXISTS(SELECT 1 FROM books WHERE id = $1)")
+        .bind(id)
+        .fetch_one(&state.pool)
+        .await?;
+
+    if !exists {
+        return Err(ApiError::not_found("book not found"));
+    }
+
+    // current_page is only stored for "reading" status
+    let current_page = if body.status == "reading" {
+        body.current_page
+    } else {
+        None
+    };
+
+    let row = sqlx::query(
+        r#"
+        INSERT INTO book_reading_progress (book_id, status, current_page, last_read_at, updated_at)
+        VALUES ($1, $2, $3, NOW(), NOW())
+        ON CONFLICT (book_id) DO UPDATE
+          SET status       = EXCLUDED.status,
+              current_page = EXCLUDED.current_page,
+              last_read_at = NOW(),
+              updated_at   = NOW()
+        RETURNING status, current_page, last_read_at
+        "#,
+    )
+    .bind(id)
+    .bind(&body.status)
+    .bind(current_page)
+    .fetch_one(&state.pool)
+    .await?;
+
+    Ok(Json(ReadingProgressResponse {
+        status: row.get("status"),
+        current_page: row.get("current_page"),
+        last_read_at: row.get("last_read_at"),
+    }))
+}

apps/api/src/search.rs

@@ -2,7 +2,7 @@ use axum::{extract::{Query, State}, Json};
 use serde::{Deserialize, Serialize};
 use utoipa::ToSchema;
 
-use crate::{error::ApiError, AppState};
+use crate::{error::ApiError, state::AppState};
 
 #[derive(Deserialize, ToSchema)]
 pub struct SearchQuery {

apps/api/src/settings.rs

@@ -6,28 +6,29 @@ use axum::{
 use serde::{Deserialize, Serialize};
 use serde_json::Value;
 use sqlx::Row;
+use utoipa::ToSchema;
 
-use crate::{error::ApiError, AppState};
+use crate::{error::ApiError, state::{AppState, load_dynamic_settings}};
 
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
 pub struct UpdateSettingRequest {
     pub value: Value,
 }
 
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
 pub struct ClearCacheResponse {
     pub success: bool,
     pub message: String,
 }
 
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
 pub struct CacheStats {
     pub total_size_mb: f64,
     pub file_count: u64,
     pub directory: String,
 }
 
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
 pub struct ThumbnailStats {
     pub total_size_mb: f64,
     pub file_count: u64,
@@ -43,7 +44,18 @@ pub fn settings_routes() -> Router<AppState> {
         .route("/settings/thumbnail/stats", get(get_thumbnail_stats))
 }
 
-async fn get_settings(State(state): State<AppState>) -> Result<Json<Value>, ApiError> {
+/// List all settings
+#[utoipa::path(
+    get,
+    path = "/settings",
+    tag = "settings",
+    responses(
+        (status = 200, description = "All settings as key/value object"),
+        (status = 401, description = "Unauthorized"),
+    ),
+    security(("Bearer" = []))
+)]
+pub async fn get_settings(State(state): State<AppState>) -> Result<Json<Value>, ApiError> {
     let rows = sqlx::query(r#"SELECT key, value FROM app_settings"#)
         .fetch_all(&state.pool)
         .await?;
@@ -58,7 +70,20 @@ async fn get_settings(State(state): State<AppState>) -> Result<Json<Value>, ApiE
     Ok(Json(Value::Object(settings)))
 }
 
-async fn get_setting(
+/// Get a single setting by key
+#[utoipa::path(
+    get,
+    path = "/settings/{key}",
+    tag = "settings",
+    params(("key" = String, Path, description = "Setting key")),
+    responses(
+        (status = 200, description = "Setting value"),
+        (status = 404, description = "Setting not found"),
+        (status = 401, description = "Unauthorized"),
+    ),
+    security(("Bearer" = []))
+)]
+pub async fn get_setting(
     State(state): State<AppState>,
     axum::extract::Path(key): axum::extract::Path<String>,
 ) -> Result<Json<Value>, ApiError> {
@@ -76,7 +101,20 @@ async fn get_setting(
     }
 }
 
-async fn update_setting(
+/// Create or update a setting
+#[utoipa::path(
+    post,
+    path = "/settings/{key}",
+    tag = "settings",
+    params(("key" = String, Path, description = "Setting key")),
+    request_body = UpdateSettingRequest,
+    responses(
+        (status = 200, description = "Updated setting value"),
+        (status = 401, description = "Unauthorized"),
+    ),
+    security(("Bearer" = []))
+)]
+pub async fn update_setting(
     State(state): State<AppState>,
     axum::extract::Path(key): axum::extract::Path<String>,
     Json(body): Json<UpdateSettingRequest>,
@@ -96,12 +134,29 @@ async fn update_setting(
     .await?;
 
     let value: Value = row.get("value");
+
+    // Rechargement des settings dynamiques si la clé affecte le comportement runtime
+    if key == "limits" || key == "image_processing" || key == "cache" {
+        let new_settings = load_dynamic_settings(&state.pool).await;
+        *state.settings.write().await = new_settings;
+    }
+
     Ok(Json(value))
 }
 
-async fn clear_cache(State(_state): State<AppState>) -> Result<Json<ClearCacheResponse>, ApiError> {
-    let cache_dir = std::env::var("IMAGE_CACHE_DIR")
-        .unwrap_or_else(|_| "/tmp/stripstream-image-cache".to_string());
+/// Clear the image page cache
+#[utoipa::path(
+    post,
+    path = "/settings/cache/clear",
+    tag = "settings",
+    responses(
+        (status = 200, body = ClearCacheResponse),
+        (status = 401, description = "Unauthorized"),
+    ),
+    security(("Bearer" = []))
+)]
+pub async fn clear_cache(State(state): State<AppState>) -> Result<Json<ClearCacheResponse>, ApiError> {
+    let cache_dir = state.settings.read().await.cache_directory.clone();
 
     let result = tokio::task::spawn_blocking(move || {
         if std::path::Path::new(&cache_dir).exists() {
@@ -128,9 +183,19 @@ async fn clear_cache(State(_state): State<AppState>) -> Result<Json<ClearCacheRe
     Ok(Json(result))
 }
 
-async fn get_cache_stats(State(_state): State<AppState>) -> Result<Json<CacheStats>, ApiError> {
-    let cache_dir = std::env::var("IMAGE_CACHE_DIR")
-        .unwrap_or_else(|_| "/tmp/stripstream-image-cache".to_string());
+/// Get image page cache statistics
+#[utoipa::path(
+    get,
+    path = "/settings/cache/stats",
+    tag = "settings",
+    responses(
+        (status = 200, body = CacheStats),
+        (status = 401, description = "Unauthorized"),
+    ),
+    security(("Bearer" = []))
+)]
+pub async fn get_cache_stats(State(state): State<AppState>) -> Result<Json<CacheStats>, ApiError> {
+    let cache_dir = state.settings.read().await.cache_directory.clone();
 
     let cache_dir_clone = cache_dir.clone();
     let stats = tokio::task::spawn_blocking(move || {
@@ -208,7 +273,18 @@ fn compute_dir_stats(path: &std::path::Path) -> (u64, u64) {
     (total_size, file_count)
 }
 
-async fn get_thumbnail_stats(State(_state): State<AppState>) -> Result<Json<ThumbnailStats>, ApiError> {
+/// Get thumbnail storage statistics
+#[utoipa::path(
+    get,
+    path = "/settings/thumbnail/stats",
+    tag = "settings",
+    responses(
+        (status = 200, body = ThumbnailStats),
+        (status = 401, description = "Unauthorized"),
+    ),
+    security(("Bearer" = []))
+)]
+pub async fn get_thumbnail_stats(State(_state): State<AppState>) -> Result<Json<ThumbnailStats>, ApiError> {
     let settings = sqlx::query(r#"SELECT value FROM app_settings WHERE key = 'thumbnail'"#)
         .fetch_optional(&_state.pool)
         .await?;

apps/api/src/state.rs

@@ -0,0 +1,136 @@
+use std::sync::{
+    atomic::AtomicU64,
+    Arc,
+};
+use std::time::Instant;
+
+use lru::LruCache;
+use sqlx::{Pool, Postgres, Row};
+use tokio::sync::{Mutex, RwLock, Semaphore};
+
+#[derive(Clone)]
+pub struct AppState {
+    pub pool: sqlx::PgPool,
+    pub bootstrap_token: Arc<str>,
+    pub meili_url: Arc<str>,
+    pub meili_master_key: Arc<str>,
+    pub page_cache: Arc<Mutex<LruCache<String, Arc<Vec<u8>>>>>,
+    pub page_render_limit: Arc<Semaphore>,
+    pub metrics: Arc<Metrics>,
+    pub read_rate_limit: Arc<Mutex<ReadRateLimit>>,
+    pub settings: Arc<RwLock<DynamicSettings>>,
+}
+
+#[derive(Clone)]
+pub struct DynamicSettings {
+    pub rate_limit_per_second: u32,
+    pub timeout_seconds: u64,
+    pub image_format: String,
+    pub image_quality: u8,
+    pub image_filter: String,
+    pub image_max_width: u32,
+    pub cache_directory: String,
+}
+
+impl Default for DynamicSettings {
+    fn default() -> Self {
+        Self {
+            rate_limit_per_second: 120,
+            timeout_seconds: 12,
+            image_format: "webp".to_string(),
+            image_quality: 85,
+            image_filter: "lanczos3".to_string(),
+            image_max_width: 2160,
+            cache_directory: std::env::var("IMAGE_CACHE_DIR")
+                .unwrap_or_else(|_| "/tmp/stripstream-image-cache".to_string()),
+        }
+    }
+}
+
+pub struct Metrics {
+    pub requests_total: AtomicU64,
+    pub page_cache_hits: AtomicU64,
+    pub page_cache_misses: AtomicU64,
+}
+
+pub struct ReadRateLimit {
+    pub window_started_at: Instant,
+    pub requests_in_window: u32,
+}
+
+impl Metrics {
+    pub fn new() -> Self {
+        Self {
+            requests_total: AtomicU64::new(0),
+            page_cache_hits: AtomicU64::new(0),
+            page_cache_misses: AtomicU64::new(0),
+        }
+    }
+}
+
+pub async fn load_concurrent_renders(pool: &Pool<Postgres>) -> usize {
+    let default_concurrency = 8;
+    let row = sqlx::query(r#"SELECT value FROM app_settings WHERE key = 'limits'"#)
+        .fetch_optional(pool)
+        .await;
+
+    match row {
+        Ok(Some(row)) => {
+            let value: serde_json::Value = row.get("value");
+            value
+                .get("concurrent_renders")
+                .and_then(|v: &serde_json::Value| v.as_u64())
+                .map(|v| v as usize)
+                .unwrap_or(default_concurrency)
+        }
+        _ => default_concurrency,
+    }
+}
+
+pub async fn load_dynamic_settings(pool: &Pool<Postgres>) -> DynamicSettings {
+    let mut s = DynamicSettings::default();
+
+    if let Ok(Some(row)) = sqlx::query(r#"SELECT value FROM app_settings WHERE key = 'limits'"#)
+        .fetch_optional(pool)
+        .await
+    {
+        let v: serde_json::Value = row.get("value");
+        if let Some(n) = v.get("rate_limit_per_second").and_then(|x| x.as_u64()) {
+            s.rate_limit_per_second = n as u32;
+        }
+        if let Some(n) = v.get("timeout_seconds").and_then(|x| x.as_u64()) {
+            s.timeout_seconds = n;
+        }
+    }
+
+    if let Ok(Some(row)) = sqlx::query(r#"SELECT value FROM app_settings WHERE key = 'image_processing'"#)
+        .fetch_optional(pool)
+        .await
+    {
+        let v: serde_json::Value = row.get("value");
+        if let Some(s2) = v.get("format").and_then(|x| x.as_str()) {
+            s.image_format = s2.to_string();
+        }
+        if let Some(n) = v.get("quality").and_then(|x| x.as_u64()) {
+            s.image_quality = n.clamp(1, 100) as u8;
+        }
+        if let Some(s2) = v.get("filter").and_then(|x| x.as_str()) {
+            s.image_filter = s2.to_string();
+        }
+        if let Some(n) = v.get("max_width").and_then(|x| x.as_u64()) {
+            s.image_max_width = n as u32;
+        }
+    }
+
+    if let Ok(Some(row)) = sqlx::query(r#"SELECT value FROM app_settings WHERE key = 'cache'"#)
+        .fetch_optional(pool)
+        .await
+    {
+        let v: serde_json::Value = row.get("value");
+        if let Some(dir) = v.get("directory").and_then(|x| x.as_str()) {
+            s.cache_directory = dir.to_string();
+        }
+    }
+
+    s
+}

apps/api/src/thumbnails.rs

@@ -1,203 +1,12 @@
-use std::path::Path;
-
-use anyhow::Context;
 use axum::{
-    extract::{Path as AxumPath, State},
-    http::StatusCode,
+    extract::State,
     Json,
 };
-use image::GenericImageView;
 use serde::Deserialize;
-use sqlx::Row;
-use tracing::{info, warn};
 use uuid::Uuid;
 use utoipa::ToSchema;
 
-use crate::{error::ApiError, index_jobs, pages, AppState};
-
-#[derive(Clone)]
-struct ThumbnailConfig {
-    enabled: bool,
-    width: u32,
-    height: u32,
-    quality: u8,
-    directory: String,
-}
-
-async fn load_thumbnail_config(pool: &sqlx::PgPool) -> ThumbnailConfig {
-    let fallback = ThumbnailConfig {
-        enabled: true,
-        width: 300,
-        height: 400,
-        quality: 80,
-        directory: "/data/thumbnails".to_string(),
-    };
-    let row = sqlx::query(r#"SELECT value FROM app_settings WHERE key = 'thumbnail'"#)
-        .fetch_optional(pool)
-        .await;
-
-    match row {
-        Ok(Some(row)) => {
-            let value: serde_json::Value = row.get("value");
-            ThumbnailConfig {
-                enabled: value
-                    .get("enabled")
-                    .and_then(|v| v.as_bool())
-                    .unwrap_or(fallback.enabled),
-                width: value
-                    .get("width")
-                    .and_then(|v| v.as_u64())
-                    .map(|v| v as u32)
-                    .unwrap_or(fallback.width),
-                height: value
-                    .get("height")
-                    .and_then(|v| v.as_u64())
-                    .map(|v| v as u32)
-                    .unwrap_or(fallback.height),
-                quality: value
-                    .get("quality")
-                    .and_then(|v| v.as_u64())
-                    .map(|v| v as u8)
-                    .unwrap_or(fallback.quality),
-                directory: value
-                    .get("directory")
-                    .and_then(|v| v.as_str())
-                    .map(|s| s.to_string())
-                    .unwrap_or_else(|| fallback.directory.clone()),
-            }
-        }
-        _ => fallback,
-    }
-}
-
-fn generate_thumbnail(image_bytes: &[u8], config: &ThumbnailConfig) -> anyhow::Result<Vec<u8>> {
-    let img = image::load_from_memory(image_bytes).context("failed to load image")?;
-    let (orig_w, orig_h) = img.dimensions();
-    let ratio_w = config.width as f32 / orig_w as f32;
-    let ratio_h = config.height as f32 / orig_h as f32;
-    let ratio = ratio_w.min(ratio_h);
-    let new_w = (orig_w as f32 * ratio) as u32;
-    let new_h = (orig_h as f32 * ratio) as u32;
-    let resized = img.resize(new_w, new_h, image::imageops::FilterType::Lanczos3);
-    let rgba = resized.to_rgba8();
-    let (w, h) = rgba.dimensions();
-    let rgb_data: Vec<u8> = rgba.pixels().flat_map(|p| [p[0], p[1], p[2]]).collect();
-    let quality = f32::max(config.quality as f32, 85.0);
-    let webp_data =
-        webp::Encoder::new(&rgb_data, webp::PixelLayout::Rgb, w, h).encode(quality);
-    Ok(webp_data.to_vec())
-}
-
-fn save_thumbnail(book_id: Uuid, thumbnail_bytes: &[u8], config: &ThumbnailConfig) -> anyhow::Result<String> {
-    let dir = Path::new(&config.directory);
-    std::fs::create_dir_all(dir)?;
-    let filename = format!("{}.webp", book_id);
-    let path = dir.join(&filename);
-    std::fs::write(&path, thumbnail_bytes)?;
-    Ok(path.to_string_lossy().to_string())
-}
-
-async fn run_checkup(state: AppState, job_id: Uuid) {
-    let pool = &state.pool;
-    let row = sqlx::query("SELECT library_id, type FROM index_jobs WHERE id = $1")
-        .bind(job_id)
-        .fetch_optional(pool)
-        .await;
-
-    let (library_id, job_type) = match row {
-        Ok(Some(r)) => (
-            r.get::<Option<Uuid>, _>("library_id"),
-            r.get::<String, _>("type"),
-        ),
-        _ => {
-            warn!("thumbnails checkup: job {} not found", job_id);
-            return;
-        }
-    };
-
-    // Regenerate: clear existing thumbnails in scope so they get regenerated
-    if job_type == "thumbnail_regenerate" {
-        let cleared = sqlx::query(
-            r#"UPDATE books SET thumbnail_path = NULL WHERE (library_id = $1 OR $1 IS NULL)"#,
-        )
-        .bind(library_id)
-        .execute(pool)
-        .await;
-        if let Ok(res) = cleared {
-            info!("thumbnails regenerate: cleared {} books", res.rows_affected());
-        }
-    }
-
-    let book_ids: Vec<Uuid> = sqlx::query_scalar(
-        r#"SELECT id FROM books WHERE (library_id = $1 OR $1 IS NULL) AND thumbnail_path IS NULL"#,
-    )
-    .bind(library_id)
-    .fetch_all(pool)
-    .await
-    .unwrap_or_default();
-
-    let config = load_thumbnail_config(pool).await;
-    if !config.enabled || book_ids.is_empty() {
-        let _ = sqlx::query(
-            "UPDATE index_jobs SET status = 'success', finished_at = NOW(), progress_percent = 100, current_file = NULL WHERE id = $1",
-        )
-        .bind(job_id)
-        .execute(pool)
-        .await;
-        return;
-    }
-
-    let total = book_ids.len() as i32;
-    let _ = sqlx::query(
-        "UPDATE index_jobs SET status = 'generating_thumbnails', total_files = $2, processed_files = 0, current_file = NULL WHERE id = $1",
-    )
-    .bind(job_id)
-    .bind(total)
-    .execute(pool)
-    .await;
-
-    for (i, &book_id) in book_ids.iter().enumerate() {
-        match pages::render_book_page_1(&state, book_id, config.width, config.quality).await {
-            Ok(page_bytes) => {
-                match generate_thumbnail(&page_bytes, &config) {
-                    Ok(thumb_bytes) => {
-                        if let Ok(path) = save_thumbnail(book_id, &thumb_bytes, &config) {
-                            if sqlx::query("UPDATE books SET thumbnail_path = $1 WHERE id = $2")
-                                .bind(&path)
-                                .bind(book_id)
-                                .execute(pool)
-                                .await
-                                .is_ok()
-                            {
-                                let processed = (i + 1) as i32;
-                                let percent = ((i + 1) as f64 / total as f64 * 100.0) as i32;
-                                let _ = sqlx::query(
-                                    "UPDATE index_jobs SET processed_files = $2, progress_percent = $3 WHERE id = $1",
-                                )
-                                .bind(job_id)
-                                .bind(processed)
-                                .bind(percent)
-                                .execute(pool)
-                                .await;
-                            }
-                        }
-                    }
-                    Err(e) => warn!("thumbnail generate failed for book {}: {:?}", book_id, e),
-                }
-            }
-            Err(e) => warn!("render page 1 failed for book {}: {:?}", book_id, e),
-        }
-    }
-
-    let _ = sqlx::query(
-        "UPDATE index_jobs SET status = 'success', finished_at = NOW(), progress_percent = 100, current_file = NULL WHERE id = $1",
-    )
-    .bind(job_id)
-    .execute(pool)
-    .await;
-
-    info!("thumbnails checkup finished for job {} ({} books)", job_id, total);
-}
+use crate::{error::ApiError, index_jobs, state::AppState};
 
 #[derive(Deserialize, ToSchema)]
 pub struct ThumbnailsRebuildRequest {
@@ -205,14 +14,14 @@ pub struct ThumbnailsRebuildRequest {
     pub library_id: Option<Uuid>,
 }
 
-/// POST /index/thumbnails/rebuild — create a job and generate thumbnails for books that don't have one (optional library scope).
+/// POST /index/thumbnails/rebuild — create a job to generate thumbnails for books that don't have one.
 #[utoipa::path(
     post,
     path = "/index/thumbnails/rebuild",
     tag = "indexing",
     request_body = Option<ThumbnailsRebuildRequest>,
     responses(
-        (status = 200, body = index_jobs::IndexJobResponse),
+        (status = 200, body = IndexJobResponse),
         (status = 401, description = "Unauthorized"),
         (status = 403, description = "Forbidden - Admin scope required"),
     ),
@@ -239,14 +48,14 @@ pub async fn start_thumbnails_rebuild(
     Ok(Json(index_jobs::map_row(row)))
 }
 
-/// POST /index/thumbnails/regenerate — create a job and regenerate all thumbnails in scope (clears then regenerates).
+/// POST /index/thumbnails/regenerate — create a job to regenerate all thumbnails (clears then regenerates).
 #[utoipa::path(
     post,
     path = "/index/thumbnails/regenerate",
     tag = "indexing",
     request_body = Option<ThumbnailsRebuildRequest>,
     responses(
-        (status = 200, body = index_jobs::IndexJobResponse),
+        (status = 200, body = IndexJobResponse),
         (status = 401, description = "Unauthorized"),
         (status = 403, description = "Forbidden - Admin scope required"),
     ),
@@ -272,13 +81,3 @@ pub async fn start_thumbnails_regenerate(
 
     Ok(Json(index_jobs::map_row(row)))
 }
-
-/// POST /index/jobs/:id/thumbnails/checkup — start thumbnail generation for books missing thumbnails (called by indexer at end of build).
-pub async fn start_checkup(
-    State(state): State<AppState>,
-    AxumPath(job_id): AxumPath<Uuid>,
-) -> Result<StatusCode, ApiError> {
-    let state = state.clone();
-    tokio::spawn(async move { run_checkup(state, job_id).await });
-    Ok(StatusCode::ACCEPTED)
-}

apps/api/src/tokens.rs

@@ -8,7 +8,7 @@ use sqlx::Row;
 use uuid::Uuid;
 use utoipa::ToSchema;
 
-use crate::{error::ApiError, AppState};
+use crate::{error::ApiError, state::AppState};
 
 #[derive(Deserialize, ToSchema)]
 pub struct CreateTokenRequest {

apps/backoffice/.env.local

@@ -1,4 +1,4 @@
-API_BASE_URL=http://localhost:8080
+API_BASE_URL=http://localhost:7080
 API_BOOTSTRAP_TOKEN=stripstream-dev-bootstrap-token
-NEXT_PUBLIC_API_BASE_URL=http://localhost:8080
+NEXT_PUBLIC_API_BASE_URL=http://localhost:7080
 NEXT_PUBLIC_API_BOOTSTRAP_TOKEN=stripstream-dev-bootstrap-token

apps/backoffice/AGENTS.md

@@ -0,0 +1,66 @@
+# apps/backoffice — Interface d'administration (Next.js)
+
+App Next.js 16 avec React 19, Tailwind CSS v4, TypeScript. Port de dev : **7082** (`npm run dev`).
+
+## Structure
+
+```
+app/
+├── layout.tsx          # Layout global (nav sticky glassmorphism, ThemeProvider)
+├── page.tsx            # Dashboard
+├── books/              # Liste et détail des livres
+├── libraries/          # Gestion bibliothèques
+├── jobs/               # Monitoring jobs
+├── tokens/             # Tokens API
+├── settings/           # Paramètres
+├── components/         # Composants métier
+│   ├── ui/             # Composants génériques (Button, Card, Badge, Icon, Input, ProgressBar, StatBox...)
+│   ├── BookCard.tsx
+│   ├── JobProgress.tsx
+│   ├── JobsList.tsx
+│   ├── LibraryForm.tsx
+│   ├── FolderBrowser.tsx / FolderPicker.tsx
+│   └── ...
+└── globals.css         # Variables CSS, Tailwind base
+lib/
+└── api.ts              # Client API : types DTO + fonctions fetch vers l'API Rust
+```
+
+## Client API (lib/api.ts)
+
+Tous les appels vers l'API Rust passent par `lib/api.ts`. Les types DTO sont définis là :
+- `LibraryDto`, `IndexJobDto`, `BookDto`, `TokenDto`, `FolderItem`
+
+Ajouter les nouveaux endpoints et types dans ce fichier.
+
+## Composants UI
+
+Les composants génériques sont dans `app/components/ui/`. Utiliser ces composants plutôt que des éléments HTML bruts :
+
+```tsx
+import { Button, Card, Badge, Icon, Input, ProgressBar, StatBox } from "@/app/components/ui";
+```
+
+## Conventions
+
+- **App Router** : toutes les pages sont des Server Components par défaut. Utiliser `"use client"` seulement pour l'interactivité.
+- **Tailwind v4** : config dans `postcss.config.js` + `tailwind.config.js`. Variables CSS dans `globals.css`.
+- **Thème** : `ThemeProvider` + `ThemeToggle` pour dark/light mode via `next-themes`.
+- **Icônes** : composant `<Icon name="..." size="sm|md|lg" />` dans `ui/Icon.tsx` — pas de librairie externe.
+- **Navigation** : routes typées dans `layout.tsx` (`"/" | "/books" | "/libraries" | "/jobs" | "/tokens" | "/settings"`).
+
+## Commandes
+
+```bash
+npm install
+npm run dev    # http://localhost:7082
+npm run build
+npm run start  # Production sur http://localhost:7082
+```
+
+## Gotchas
+
+- **Port 7082** : pas le port Next.js par défaut (3000). Défini dans `package.json` scripts (`-p 7082`).
+- **API_BASE_URL** : en prod, configuré via env. En dev local, l'API doit tourner sur `http://localhost:7080`.
+- **React 19 + Next.js 16** : utiliser les nouvelles APIs (actions serveur, `use()` hook) si disponibles.
+- **Pas de gestion d'état global** : fetch direct depuis les Server Components ou `useState`/`useEffect` dans les Client Components.

apps/backoffice/Dockerfile

@@ -12,11 +12,11 @@ RUN npm run build
 FROM node:22-alpine AS runner
 WORKDIR /app
 ENV NODE_ENV=production
-ENV PORT=8082
+ENV PORT=7082
 ENV HOST=0.0.0.0
 RUN apk add --no-cache wget
 COPY --from=builder /app/.next/standalone ./
 COPY --from=builder /app/.next/static ./.next/static
 COPY --from=builder /app/public ./public
-EXPOSE 8082
+EXPOSE 7082
 CMD ["node", "server.js"]

apps/backoffice/app/api/books/[bookId]/convert/route.ts

@@ -0,0 +1,17 @@
+import { NextRequest, NextResponse } from "next/server";
+import { convertBook } from "@/lib/api";
+
+export async function POST(
+  _request: NextRequest,
+  { params }: { params: Promise<{ bookId: string }> }
+) {
+  const { bookId } = await params;
+  try {
+    const data = await convertBook(bookId);
+    return NextResponse.json(data);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Failed to start conversion";
+    const status = message.includes("409") ? 409 : 500;
+    return NextResponse.json({ error: message }, { status });
+  }
+}

apps/backoffice/app/api/books/[bookId]/pages/[pageNum]/route.ts

@@ -1,35 +1,25 @@
 import { NextRequest, NextResponse } from "next/server";
+import { config } from "@/lib/api";
 
 export async function GET(
   request: NextRequest,
   { params }: { params: Promise<{ bookId: string; pageNum: string }> }
 ) {
   const { bookId, pageNum } = await params;
-  
-  // Récupérer les query params (format, width, quality)
-  const { searchParams } = new URL(request.url);
-  const format = searchParams.get("format") || "webp";
-  const width = searchParams.get("width") || "";
-  const quality = searchParams.get("quality") || "";
-  
-  // Construire l'URL vers l'API backend
-  const apiBaseUrl = process.env.API_BASE_URL || "http://api:8080";
-  const apiUrl = new URL(`${apiBaseUrl}/books/${bookId}/pages/${pageNum}`);
-  apiUrl.searchParams.set("format", format);
-  if (width) apiUrl.searchParams.set("width", width);
-  if (quality) apiUrl.searchParams.set("quality", quality);
-  
-  // Faire la requête à l'API
-  const token = process.env.API_BOOTSTRAP_TOKEN;
-  if (!token) {
-    return new NextResponse("API token not configured", { status: 500 });
-  }
-  
   try {
+    const { baseUrl, token } = config();
+    const { searchParams } = new URL(request.url);
+    const format = searchParams.get("format") || "webp";
+    const width = searchParams.get("width") || "";
+    const quality = searchParams.get("quality") || "";
+
+    const apiUrl = new URL(`${baseUrl}/books/${bookId}/pages/${pageNum}`);
+    apiUrl.searchParams.set("format", format);
+    if (width) apiUrl.searchParams.set("width", width);
+    if (quality) apiUrl.searchParams.set("quality", quality);
+
     const response = await fetch(apiUrl.toString(), {
-      headers: {
-        Authorization: `Bearer ${token}`,
-      },
+      headers: { Authorization: `Bearer ${token}` },
     });
     
     if (!response.ok) {

apps/backoffice/app/api/books/[bookId]/thumbnail/route.ts

@@ -1,4 +1,5 @@
 import { NextRequest, NextResponse } from "next/server";
+import { config } from "@/lib/api";
 
 export async function GET(
   request: NextRequest,
@@ -6,19 +7,10 @@ export async function GET(
 ) {
   const { bookId } = await params;
   
-  const apiBaseUrl = process.env.API_BASE_URL || "http://api:8080";
-  const apiUrl = `${apiBaseUrl}/books/${bookId}/thumbnail`;
-  
-  const token = process.env.API_BOOTSTRAP_TOKEN;
-  if (!token) {
-    return new NextResponse("API token not configured", { status: 500 });
-  }
-  
   try {
-    const response = await fetch(apiUrl, {
-      headers: {
-        Authorization: `Bearer ${token}`,
-      },
+    const { baseUrl, token } = config();
+    const response = await fetch(`${baseUrl}/books/${bookId}/thumbnail`, {
+      headers: { Authorization: `Bearer ${token}` },
     });
     
     if (!response.ok) {

apps/backoffice/app/api/folders/route.ts

@@ -1,39 +1,13 @@
 import { NextRequest, NextResponse } from "next/server";
+import { listFolders } from "@/lib/api";
 
 export async function GET(request: NextRequest) {
-  const apiBaseUrl = process.env.API_BASE_URL || "http://api:8080";
-  const apiToken = process.env.API_BOOTSTRAP_TOKEN;
-  
-  if (!apiToken) {
-    return NextResponse.json({ error: "API token not configured" }, { status: 500 });
-  }
-  
   try {
     const { searchParams } = new URL(request.url);
-    const path = searchParams.get("path");
-    
-    let apiUrl = `${apiBaseUrl}/folders`;
-    if (path) {
-      apiUrl += `?path=${encodeURIComponent(path)}`;
-    }
-    
-    const response = await fetch(apiUrl, {
-      headers: {
-        Authorization: `Bearer ${apiToken}`,
-      },
-    });
-    
-    if (!response.ok) {
-      return NextResponse.json(
-        { error: `API error: ${response.status}` },
-        { status: response.status }
-      );
-    }
-    
-    const data = await response.json();
+    const path = searchParams.get("path") || undefined;
+    const data = await listFolders(path);
     return NextResponse.json(data);
   } catch (error) {
-    console.error("Proxy error:", error);
     return NextResponse.json({ error: "Failed to fetch folders" }, { status: 500 });
   }
 }

apps/backoffice/app/api/jobs/[id]/cancel/route.ts

@@ -1,36 +1,15 @@
 import { NextRequest, NextResponse } from "next/server";
+import { cancelJob } from "@/lib/api";
 
 export async function POST(
-  request: NextRequest,
+  _request: NextRequest,
   { params }: { params: Promise<{ id: string }> }
 ) {
   const { id } = await params;
-  const apiBaseUrl = process.env.API_BASE_URL || "http://api:8080";
-  const apiToken = process.env.API_BOOTSTRAP_TOKEN;
-  
-  if (!apiToken) {
-    return NextResponse.json({ error: "API token not configured" }, { status: 500 });
-  }
-  
   try {
-    const response = await fetch(`${apiBaseUrl}/index/cancel/${id}`, {
-      method: "POST",
-      headers: {
-        Authorization: `Bearer ${apiToken}`,
-      },
-    });
-    
-    if (!response.ok) {
-      return NextResponse.json(
-        { error: `API error: ${response.status}` },
-        { status: response.status }
-      );
-    }
-    
-    const data = await response.json();
+    const data = await cancelJob(id);
     return NextResponse.json(data);
   } catch (error) {
-    console.error("Proxy error:", error);
     return NextResponse.json({ error: "Failed to cancel job" }, { status: 500 });
   }
 }

apps/backoffice/app/api/jobs/[id]/route.ts

@@ -1,35 +1,15 @@
 import { NextRequest, NextResponse } from "next/server";
+import { apiFetch, IndexJobDto } from "@/lib/api";
 
 export async function GET(
-  request: NextRequest,
+  _request: NextRequest,
   { params }: { params: Promise<{ id: string }> }
 ) {
   const { id } = await params;
-  const apiBaseUrl = process.env.API_BASE_URL || "http://api:8080";
-  const apiToken = process.env.API_BOOTSTRAP_TOKEN;
-  
-  if (!apiToken) {
-    return NextResponse.json({ error: "API token not configured" }, { status: 500 });
-  }
-  
   try {
-    const response = await fetch(`${apiBaseUrl}/index/jobs/${id}`, {
-      headers: {
-        Authorization: `Bearer ${apiToken}`,
-      },
-    });
-    
-    if (!response.ok) {
-      return NextResponse.json(
-        { error: `API error: ${response.status}` },
-        { status: response.status }
-      );
-    }
-    
-    const data = await response.json();
+    const data = await apiFetch<IndexJobDto>(`/index/jobs/${id}`);
     return NextResponse.json(data);
   } catch (error) {
-    console.error("Proxy error:", error);
     return NextResponse.json({ error: "Failed to fetch job" }, { status: 500 });
   }
 }

apps/backoffice/app/api/jobs/[id]/stream/route.ts

@@ -1,20 +1,13 @@
 import { NextRequest } from "next/server";
+import { config } from "@/lib/api";
 
 export async function GET(
   request: NextRequest,
   { params }: { params: Promise<{ id: string }> }
 ) {
   const { id } = await params;
-  const apiBaseUrl = process.env.API_BASE_URL || "http://api:8080";
-  const apiToken = process.env.API_BOOTSTRAP_TOKEN;
-  
-  if (!apiToken) {
-    return new Response(
-      `data: ${JSON.stringify({ error: "API token not configured" })}\n\n`,
-      { status: 500, headers: { "Content-Type": "text/event-stream" } }
-    );
-  }
-  
+  const { baseUrl, token } = config();
+
   const stream = new ReadableStream({
     async start(controller) {
       // Send initial headers for SSE
@@ -27,10 +20,8 @@ export async function GET(
         if (!isActive) return;
         
         try {
-          const response = await fetch(`${apiBaseUrl}/index/jobs/${id}`, {
-            headers: {
-              Authorization: `Bearer ${apiToken}`,
-            },
+          const response = await fetch(`${baseUrl}/index/jobs/${id}`, {
+            headers: { Authorization: `Bearer ${token}` },
           });
           
           if (response.ok && isActive) {

apps/backoffice/app/api/jobs/active/route.ts

@@ -0,0 +1,11 @@
+import { NextResponse } from "next/server";
+import { apiFetch, IndexJobDto } from "@/lib/api";
+
+export async function GET() {
+  try {
+    const data = await apiFetch<IndexJobDto[]>("/index/jobs/active");
+    return NextResponse.json(data);
+  } catch (error) {
+    return NextResponse.json({ error: "Failed to fetch active jobs" }, { status: 500 });
+  }
+}

apps/backoffice/app/api/jobs/route.ts

@@ -1,31 +0,0 @@
-import { NextRequest, NextResponse } from "next/server";
-
-export async function GET(request: NextRequest) {
-  const apiBaseUrl = process.env.API_BASE_URL || "http://api:8080";
-  const apiToken = process.env.API_BOOTSTRAP_TOKEN;
-  
-  if (!apiToken) {
-    return NextResponse.json({ error: "API token not configured" }, { status: 500 });
-  }
-  
-  try {
-    const response = await fetch(`${apiBaseUrl}/index/status`, {
-      headers: {
-        Authorization: `Bearer ${apiToken}`,
-      },
-    });
-    
-    if (!response.ok) {
-      return NextResponse.json(
-        { error: `API error: ${response.status}` },
-        { status: response.status }
-      );
-    }
-    
-    const data = await response.json();
-    return NextResponse.json(data);
-  } catch (error) {
-    console.error("Proxy error:", error);
-    return NextResponse.json({ error: "Failed to fetch jobs" }, { status: 500 });
-  }
-}

apps/backoffice/app/api/jobs/stream/route.ts

@@ -1,16 +1,9 @@
 import { NextRequest } from "next/server";
+import { config } from "@/lib/api";
 
 export async function GET(request: NextRequest) {
-  const apiBaseUrl = process.env.API_BASE_URL || "http://api:8080";
-  const apiToken = process.env.API_BOOTSTRAP_TOKEN;
-  
-  if (!apiToken) {
-    return new Response(
-      `data: ${JSON.stringify({ error: "API token not configured" })}\n\n`,
-      { status: 500, headers: { "Content-Type": "text/event-stream" } }
-    );
-  }
-  
+  const { baseUrl, token } = config();
+
   const stream = new ReadableStream({
     async start(controller) {
       controller.enqueue(new TextEncoder().encode(""));
@@ -22,10 +15,8 @@ export async function GET(request: NextRequest) {
         if (!isActive) return;
         
         try {
-          const response = await fetch(`${apiBaseUrl}/index/status`, {
-            headers: {
-              Authorization: `Bearer ${apiToken}`,
-            },
+          const response = await fetch(`${baseUrl}/index/status`, {
+            headers: { Authorization: `Bearer ${token}` },
           });
           
           if (response.ok && isActive) {

apps/backoffice/app/api/libraries/[id]/monitoring/route.ts

@@ -0,0 +1,18 @@
+import { NextRequest, NextResponse } from "next/server";
+import { updateLibraryMonitoring } from "@/lib/api";
+
+export async function PATCH(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  const { id } = await params;
+  try {
+    const { monitor_enabled, scan_mode, watcher_enabled } = await request.json();
+    const data = await updateLibraryMonitoring(id, monitor_enabled, scan_mode, watcher_enabled);
+    return NextResponse.json(data);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Failed to update monitoring settings";
+    console.error("[monitoring PATCH]", message);
+    return NextResponse.json({ error: message }, { status: 500 });
+  }
+}

apps/backoffice/app/api/settings/[key]/route.ts

@@ -1,29 +1,16 @@
 import { NextRequest, NextResponse } from "next/server";
+import { apiFetch, updateSetting } from "@/lib/api";
 
 export async function GET(
-  request: NextRequest,
+  _request: NextRequest,
   { params }: { params: Promise<{ key: string }> }
 ) {
+  const { key } = await params;
   try {
-    const { key } = await params;
-    const baseUrl = process.env.API_BASE_URL || "http://api:8080";
-    const token = process.env.API_BOOTSTRAP_TOKEN;
-    
-    const response = await fetch(`${baseUrl}/settings/${key}`, {
-      headers: {
-        Authorization: `Bearer ${token}`,
-      },
-      cache: "no-store"
-    });
-
-    if (!response.ok) {
-      return NextResponse.json({ error: "Failed to fetch setting" }, { status: response.status });
-    }
-
-    const data = await response.json();
+    const data = await apiFetch<unknown>(`/settings/${key}`);
     return NextResponse.json(data);
   } catch (error) {
-    return NextResponse.json({ error: "Internal server error" }, { status: 500 });
+    return NextResponse.json({ error: "Failed to fetch setting" }, { status: 500 });
   }
 }
 
@@ -31,29 +18,12 @@ export async function POST(
   request: NextRequest,
   { params }: { params: Promise<{ key: string }> }
 ) {
+  const { key } = await params;
   try {
-    const { key } = await params;
-    const baseUrl = process.env.API_BASE_URL || "http://api:8080";
-    const token = process.env.API_BOOTSTRAP_TOKEN;
-    const body = await request.json();
-    
-    const response = await fetch(`${baseUrl}/settings/${key}`, {
-      method: "POST",
-      headers: {
-        Authorization: `Bearer ${token}`,
-        "Content-Type": "application/json",
-      },
-      body: JSON.stringify(body),
-      cache: "no-store"
-    });
-
-    if (!response.ok) {
-      return NextResponse.json({ error: "Failed to update setting" }, { status: response.status });
-    }
-
-    const data = await response.json();
+    const { value } = await request.json();
+    const data = await updateSetting(key, value);
     return NextResponse.json(data);
   } catch (error) {
-    return NextResponse.json({ error: "Internal server error" }, { status: 500 });
+    return NextResponse.json({ error: "Failed to update setting" }, { status: 500 });
   }
 }

apps/backoffice/app/api/settings/cache/clear/route.ts

@@ -1,25 +1,11 @@
-import { NextRequest, NextResponse } from "next/server";
+import { NextResponse } from "next/server";
+import { clearCache } from "@/lib/api";
 
-export async function POST(request: NextRequest) {
+export async function POST() {
   try {
-    const baseUrl = process.env.API_BASE_URL || "http://api:8080";
-    const token = process.env.API_BOOTSTRAP_TOKEN;
-    
-    const response = await fetch(`${baseUrl}/settings/cache/clear`, {
-      method: "POST",
-      headers: {
-        Authorization: `Bearer ${token}`,
-      },
-      cache: "no-store"
-    });
-
-    if (!response.ok) {
-      return NextResponse.json({ error: "Failed to clear cache" }, { status: response.status });
-    }
-
-    const data = await response.json();
+    const data = await clearCache();
     return NextResponse.json(data);
   } catch (error) {
-    return NextResponse.json({ error: "Internal server error" }, { status: 500 });
+    return NextResponse.json({ error: "Failed to clear cache" }, { status: 500 });
   }
 }

apps/backoffice/app/api/settings/cache/stats/route.ts

@@ -1,24 +1,11 @@
-import { NextRequest, NextResponse } from "next/server";
+import { NextResponse } from "next/server";
+import { getCacheStats } from "@/lib/api";
 
-export async function GET(request: NextRequest) {
+export async function GET() {
   try {
-    const baseUrl = process.env.API_BASE_URL || "http://api:8080";
-    const token = process.env.API_BOOTSTRAP_TOKEN;
-    
-    const response = await fetch(`${baseUrl}/settings/cache/stats`, {
-      headers: {
-        Authorization: `Bearer ${token}`,
-      },
-      cache: "no-store"
-    });
-
-    if (!response.ok) {
-      return NextResponse.json({ error: "Failed to fetch cache stats" }, { status: response.status });
-    }
-
-    const data = await response.json();
+    const data = await getCacheStats();
     return NextResponse.json(data);
   } catch (error) {
-    return NextResponse.json({ error: "Internal server error" }, { status: 500 });
+    return NextResponse.json({ error: "Failed to fetch cache stats" }, { status: 500 });
   }
 }

apps/backoffice/app/api/settings/route.ts

@@ -1,24 +0,0 @@
-import { NextRequest, NextResponse } from "next/server";
-
-export async function GET(request: NextRequest) {
-  try {
-    const baseUrl = process.env.API_BASE_URL || "http://api:8080";
-    const token = process.env.API_BOOTSTRAP_TOKEN;
-    
-    const response = await fetch(`${baseUrl}/settings`, {
-      headers: {
-        Authorization: `Bearer ${token}`,
-      },
-      cache: "no-store"
-    });
-
-    if (!response.ok) {
-      return NextResponse.json({ error: "Failed to fetch settings" }, { status: response.status });
-    }
-
-    const data = await response.json();
-    return NextResponse.json(data);
-  } catch (error) {
-    return NextResponse.json({ error: "Internal server error" }, { status: 500 });
-  }
-}

apps/backoffice/app/books/[id]/page.tsx

@@ -1,10 +1,43 @@
-import { fetchLibraries, getBookCoverUrl, BookDto, apiFetch } from "../../../lib/api";
+import { fetchLibraries, getBookCoverUrl, BookDto, apiFetch, ReadingStatus } from "../../../lib/api";
+import { BookPreview } from "../../components/BookPreview";
+import { ConvertButton } from "../../components/ConvertButton";
 import Image from "next/image";
 import Link from "next/link";
 import { notFound } from "next/navigation";
 
 export const dynamic = "force-dynamic";
 
+const readingStatusConfig: Record<ReadingStatus, { label: string; className: string }> = {
+  unread: { label: "Non lu", className: "bg-muted/60 text-muted-foreground border border-border" },
+  reading: { label: "En cours", className: "bg-amber-500/15 text-amber-600 dark:text-amber-400 border border-amber-500/30" },
+  read: { label: "Lu", className: "bg-green-500/15 text-green-600 dark:text-green-400 border border-green-500/30" },
+};
+
+function ReadingStatusBadge({
+  status,
+  currentPage,
+  lastReadAt,
+}: {
+  status: ReadingStatus;
+  currentPage: number | null;
+  lastReadAt: string | null;
+}) {
+  const { label, className } = readingStatusConfig[status];
+  return (
+    <div className="flex items-center gap-2">
+      <span className={`inline-flex items-center px-2.5 py-0.5 rounded-full text-xs font-semibold ${className}`}>
+        {label}
+        {status === "reading" && currentPage != null && ` · p. ${currentPage}`}
+      </span>
+      {lastReadAt && (
+        <span className="text-xs text-muted-foreground">
+          {new Date(lastReadAt).toLocaleDateString()}
+        </span>
+      )}
+    </div>
+  );
+}
+
 async function fetchBook(bookId: string): Promise<BookDto | null> {
   try {
     return await apiFetch<BookDto>(`/books/${bookId}`);
@@ -69,6 +102,17 @@ export default async function BookDetailPage({
             )}
 
             <div className="space-y-3">
+              {book.reading_status && (
+                <div className="flex items-center justify-between py-2 border-b border-border">
+                  <span className="text-sm text-muted-foreground">Lecture :</span>
+                  <ReadingStatusBadge
+                    status={book.reading_status}
+                    currentPage={book.reading_current_page ?? null}
+                    lastReadAt={book.reading_last_read_at ?? null}
+                  />
+                </div>
+              )}
+
               <div className="flex items-center justify-between py-2 border-b border-border">
                 <span className="text-sm text-muted-foreground">Format:</span>
                 <span className={`inline-flex px-2.5 py-1 rounded-full text-xs font-semibold ${
@@ -114,7 +158,10 @@ export default async function BookDetailPage({
               {book.file_format && (
                 <div className="flex items-center justify-between py-2 border-b border-border">
                   <span className="text-sm text-muted-foreground">File Format:</span>
-                  <span className="text-sm text-foreground">{book.file_format.toUpperCase()}</span>
+                  <div className="flex items-center gap-3">
+                    <span className="text-sm text-foreground">{book.file_format.toUpperCase()}</span>
+                    {book.file_format === "cbr" && <ConvertButton bookId={book.id} />}
+                  </div>
                 </div>
               )}
 
@@ -157,6 +204,12 @@ export default async function BookDetailPage({
           </div>
         </div>
       </div>
+
+      {book.page_count && book.page_count > 0 && (
+        <div className="mt-8">
+          <BookPreview bookId={book.id} pageCount={book.page_count} />
+        </div>
+      )}
     </>
   );
 }

apps/backoffice/app/components/BookCard.tsx

@@ -3,10 +3,17 @@
 import { useState } from "react";
 import Image from "next/image";
 import Link from "next/link";
-import { BookDto } from "../../lib/api";
+import { BookDto, ReadingStatus } from "../../lib/api";
+
+const readingStatusOverlay: Record<ReadingStatus, { label: string; className: string } | null> = {
+  unread: null,
+  reading: { label: "En cours", className: "bg-amber-500/90 text-white" },
+  read: { label: "Lu", className: "bg-green-600/90 text-white" },
+};
 
 interface BookCardProps {
   book: BookDto & { coverUrl?: string };
+  readingStatus?: ReadingStatus;
 }
 
 function BookImage({ src, alt }: { src: string; alt: string }) {
@@ -37,18 +44,27 @@ function BookImage({ src, alt }: { src: string; alt: string }) {
   );
 }
 
-export function BookCard({ book }: BookCardProps) {
+export function BookCard({ book, readingStatus }: BookCardProps) {
   const coverUrl = book.coverUrl || `/api/books/${book.id}/thumbnail`;
-  
+  const status = readingStatus ?? book.reading_status;
+  const overlay = status ? readingStatusOverlay[status] : null;
+
   return (
-    <Link 
-      href={`/books/${book.id}`} 
+    <Link
+      href={`/books/${book.id}`}
       className="group block bg-card rounded-xl border border-border/60 shadow-sm hover:shadow-md hover:-translate-y-1 transition-all duration-200 overflow-hidden"
     >
-      <BookImage 
-        src={coverUrl}
-        alt={`Cover of ${book.title}`}
-      />
+      <div className="relative">
+        <BookImage
+          src={coverUrl}
+          alt={`Cover of ${book.title}`}
+        />
+        {overlay && (
+          <span className={`absolute bottom-2 left-2 px-2 py-0.5 rounded-full text-[10px] font-bold tracking-wide ${overlay.className}`}>
+            {overlay.label}
+          </span>
+        )}
+      </div>
       
       {/* Book Info */}
       <div className="p-4">

apps/backoffice/app/components/BookPreview.tsx

@@ -0,0 +1,60 @@
+"use client";
+
+import { useState } from "react";
+import Image from "next/image";
+
+const PAGE_SIZE = 5;
+
+export function BookPreview({ bookId, pageCount }: { bookId: string; pageCount: number }) {
+  const [offset, setOffset] = useState(0);
+
+  const pages = Array.from({ length: PAGE_SIZE }, (_, i) => offset + i + 1).filter(
+    (p) => p <= pageCount
+  );
+
+  return (
+    <div className="bg-card rounded-xl border border-border p-6">
+      <div className="flex items-center justify-between mb-4">
+        <h2 className="text-lg font-semibold text-foreground">
+          Preview
+          <span className="ml-2 text-sm font-normal text-muted-foreground">
+            pages {offset + 1}–{Math.min(offset + PAGE_SIZE, pageCount)} / {pageCount}
+          </span>
+        </h2>
+        <div className="flex gap-2">
+          <button
+            onClick={() => setOffset((o) => Math.max(0, o - PAGE_SIZE))}
+            disabled={offset === 0}
+            className="px-3 py-1.5 text-sm rounded-lg border border-border bg-muted/50 text-foreground hover:bg-muted disabled:opacity-40 disabled:cursor-not-allowed transition-colors"
+          >
+            ← Prev
+          </button>
+          <button
+            onClick={() => setOffset((o) => Math.min(o + PAGE_SIZE, pageCount - 1))}
+            disabled={offset + PAGE_SIZE >= pageCount}
+            className="px-3 py-1.5 text-sm rounded-lg border border-border bg-muted/50 text-foreground hover:bg-muted disabled:opacity-40 disabled:cursor-not-allowed transition-colors"
+          >
+            Next →
+          </button>
+        </div>
+      </div>
+
+      <div className="grid grid-cols-5 gap-3">
+        {pages.map((pageNum) => (
+          <div key={pageNum} className="flex flex-col items-center gap-1.5">
+            <div className="relative w-full aspect-[2/3] bg-muted rounded-lg overflow-hidden border border-border">
+              <Image
+                src={`/api/books/${bookId}/pages/${pageNum}?format=webp&width=600&quality=80`}
+                alt={`Page ${pageNum}`}
+                fill
+                className="object-contain"
+                unoptimized
+              />
+            </div>
+            <span className="text-xs text-muted-foreground">{pageNum}</span>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}

apps/backoffice/app/components/ConvertButton.tsx

@@ -0,0 +1,71 @@
+"use client";
+
+import { useState } from "react";
+import Link from "next/link";
+import { Button } from "./ui";
+
+interface ConvertButtonProps {
+  bookId: string;
+}
+
+type ConvertState =
+  | { type: "idle" }
+  | { type: "loading" }
+  | { type: "success"; jobId: string }
+  | { type: "error"; message: string };
+
+export function ConvertButton({ bookId }: ConvertButtonProps) {
+  const [state, setState] = useState<ConvertState>({ type: "idle" });
+
+  const handleConvert = async () => {
+    setState({ type: "loading" });
+    try {
+      const res = await fetch(`/api/books/${bookId}/convert`, { method: "POST" });
+      if (!res.ok) {
+        const body = await res.json().catch(() => ({ error: res.statusText }));
+        setState({ type: "error", message: body.error || "Conversion failed" });
+        return;
+      }
+      const job = await res.json();
+      setState({ type: "success", jobId: job.id });
+    } catch (err) {
+      setState({ type: "error", message: err instanceof Error ? err.message : "Unknown error" });
+    }
+  };
+
+  if (state.type === "success") {
+    return (
+      <div className="flex items-center gap-2 text-sm text-success">
+        <span>Conversion started.</span>
+        <Link href={`/jobs/${state.jobId}`} className="text-primary hover:underline font-medium">
+          View job →
+        </Link>
+      </div>
+    );
+  }
+
+  if (state.type === "error") {
+    return (
+      <div className="flex flex-col gap-1">
+        <span className="text-sm text-destructive">{state.message}</span>
+        <button
+          className="text-xs text-muted-foreground hover:underline text-left"
+          onClick={() => setState({ type: "idle" })}
+        >
+          Dismiss
+        </button>
+      </div>
+    );
+  }
+
+  return (
+    <Button
+      variant="secondary"
+      size="sm"
+      onClick={handleConvert}
+      disabled={state.type === "loading"}
+    >
+      {state.type === "loading" ? "Converting…" : "Convert to CBZ"}
+    </Button>
+  );
+}

apps/backoffice/app/components/JobRow.tsx

@@ -3,7 +3,7 @@
 import { useState } from "react";
 import Link from "next/link";
 import { JobProgress } from "./JobProgress";
-import { StatusBadge, Button, MiniProgressBar } from "./ui";
+import { StatusBadge, JobTypeBadge, Button, MiniProgressBar } from "./ui";
 
 interface JobRowProps {
   job: {
@@ -93,7 +93,9 @@ export function JobRow({ job, libraryName, highlighted, onCancel, formatDate, fo
         <td className="px-4 py-3 text-sm text-foreground">
           {job.library_id ? libraryName || job.library_id.slice(0, 8) : "—"}
         </td>
-        <td className="px-4 py-3 text-sm text-foreground">{job.type}</td>
+        <td className="px-4 py-3">
+          <JobTypeBadge type={job.type} />
+        </td>
         <td className="px-4 py-3">
           <div className="flex items-center gap-2 flex-wrap">
             <StatusBadge status={job.status} />

apps/backoffice/app/components/JobsIndicator.tsx

@@ -146,15 +146,27 @@ export function JobsIndicator() {
         />
       </button>
 
+      {/* Backdrop mobile */}
+      {isOpen && (
+        <div
+          className="fixed inset-0 z-40 sm:hidden bg-background/60 backdrop-blur-sm"
+          onClick={() => setIsOpen(false)}
+          aria-hidden="true"
+        />
+      )}
+
       {/* Popin/Dropdown with glassmorphism */}
       {isOpen && (
         <div className="
-          absolute right-0 top-full mt-2 w-96 
+          fixed sm:absolute
+          inset-x-3 sm:inset-x-auto
+          top-[4.5rem] sm:top-full sm:mt-2
+          sm:w-96
           bg-popover/95 backdrop-blur-md
-          rounded-xl 
-          shadow-elevation-2 
-          border border-border/60 
-          overflow-hidden 
+          rounded-xl
+          shadow-elevation-2
+          border border-border/60
+          overflow-hidden
           z-50
           animate-scale-in
         ">

apps/backoffice/app/components/LibraryActions.tsx

@@ -20,6 +20,7 @@ export function LibraryActions({
 }: LibraryActionsProps) {
   const [isOpen, setIsOpen] = useState(false);
   const [isPending, startTransition] = useTransition();
+  const [saveError, setSaveError] = useState<string | null>(null);
   const dropdownRef = useRef<HTMLDivElement>(null);
 
   useEffect(() => {
@@ -33,11 +34,12 @@ export function LibraryActions({
   }, []);
 
   const handleSubmit = (formData: FormData) => {
+    setSaveError(null);
     startTransition(async () => {
       const monitorEnabled = formData.get("monitor_enabled") === "true";
       const watcherEnabled = formData.get("watcher_enabled") === "true";
       const scanMode = formData.get("scan_mode") as string;
-      
+
       try {
         const response = await fetch(`/api/libraries/${libraryId}/monitoring`, {
           method: "PATCH",
@@ -48,17 +50,20 @@ export function LibraryActions({
             watcher_enabled: watcherEnabled,
           }),
         });
-        
+
         if (response.ok) {
           setIsOpen(false);
           window.location.reload();
         } else {
-          console.error("Failed to save settings:", response.statusText);
-          alert("Failed to save settings. Please try again.");
+          const body = await response.json().catch(() => ({}));
+          const msg = body?.error || `HTTP ${response.status}`;
+          console.error("Failed to save settings:", msg);
+          setSaveError(msg);
         }
       } catch (error) {
-        console.error("Failed to save settings:", error);
-        alert("Failed to save settings. Please try again.");
+        const msg = error instanceof Error ? error.message : "Network error";
+        console.error("Failed to save settings:", msg);
+        setSaveError(msg);
       }
     });
   };
@@ -121,9 +126,15 @@ export function LibraryActions({
                 </select>
               </div>
 
-              <Button 
-                type="submit" 
-                size="sm" 
+              {saveError && (
+                <p className="text-xs text-destructive bg-destructive/10 px-2 py-1.5 rounded-lg break-all">
+                  {saveError}
+                </p>
+              )}
+
+              <Button
+                type="submit"
+                size="sm"
                 className="w-full"
                 disabled={isPending}
               >

apps/backoffice/app/components/MobileNav.tsx

@@ -0,0 +1,93 @@
+"use client";
+
+import { useState, useEffect } from "react";
+import { createPortal } from "react-dom";
+import Link from "next/link";
+import { NavIcon } from "./ui";
+
+type NavItem = {
+  href: "/" | "/books" | "/libraries" | "/jobs" | "/tokens" | "/settings";
+  label: string;
+  icon: "dashboard" | "books" | "libraries" | "jobs" | "tokens" | "settings";
+};
+
+const HamburgerIcon = () => (
+  <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth={2} className="w-5 h-5">
+    <path d="M3 6h18M3 12h18M3 18h18" strokeLinecap="round" />
+  </svg>
+);
+
+const XIcon = () => (
+  <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth={2} className="w-5 h-5">
+    <path d="M18 6L6 18M6 6l12 12" strokeLinecap="round" />
+  </svg>
+);
+
+export function MobileNav({ navItems }: { navItems: NavItem[] }) {
+  const [isOpen, setIsOpen] = useState(false);
+  const [mounted, setMounted] = useState(false);
+
+  useEffect(() => {
+    setMounted(true);
+  }, []);
+
+  const overlay = (
+    <>
+      {/* Backdrop */}
+      <div
+        className={`fixed inset-0 z-[60] bg-background/80 backdrop-blur-sm md:hidden transition-opacity duration-300 ${isOpen ? "opacity-100" : "opacity-0 pointer-events-none"}`}
+        onClick={() => setIsOpen(false)}
+        aria-hidden="true"
+      />
+
+      {/* Drawer */}
+      <div
+        className={`
+          fixed inset-y-0 left-0 z-[70] w-64
+          bg-background/95 backdrop-blur-xl
+          border-r border-border/60
+          flex flex-col
+          transform transition-transform duration-300 ease-in-out
+          md:hidden
+          ${isOpen ? "translate-x-0" : "-translate-x-full"}
+        `}
+      >
+        <div className="h-16 border-b border-border/40 flex items-center px-4">
+          <span className="text-sm font-semibold text-muted-foreground tracking-wide uppercase">Navigation</span>
+        </div>
+
+        <nav className="flex flex-col gap-1 p-3 flex-1">
+          {navItems.map((item) => (
+            <Link
+              key={item.href}
+              href={item.href}
+              className="flex items-center gap-3 px-3 py-3 rounded-lg text-muted-foreground hover:text-foreground hover:bg-accent transition-colors duration-200 active:scale-[0.98]"
+              onClick={() => setIsOpen(false)}
+            >
+              <NavIcon name={item.icon} />
+              <span className="font-medium">{item.label}</span>
+            </Link>
+          ))}
+        </nav>
+      </div>
+    </>
+  );
+
+  return (
+    <>
+      {/* Hamburger button — reste dans le header */}
+      <button
+        className="md:hidden p-2 rounded-lg text-muted-foreground hover:text-foreground hover:bg-accent transition-colors"
+        onClick={() => setIsOpen(!isOpen)}
+        aria-label={isOpen ? "Close menu" : "Open menu"}
+        aria-expanded={isOpen}
+      >
+        {isOpen ? <XIcon /> : <HamburgerIcon />}
+      </button>
+
+      {/* Backdrop + Drawer portés directement sur document.body,
+          hors du header et de son backdrop-filter */}
+      {mounted && createPortal(overlay, document.body)}
+    </>
+  );
+}

apps/backoffice/app/components/ui/Badge.tsx

@@ -94,8 +94,11 @@ const jobTypeVariants: Record<string, BadgeVariant> = {
 };
 
 const jobTypeLabels: Record<string, string> = {
+  rebuild: "Index",
+  full_rebuild: "Full Index",
   thumbnail_rebuild: "Thumbnails",
-  thumbnail_regenerate: "Regenerate",
+  thumbnail_regenerate: "Regen. Thumbnails",
+  cbr_to_cbz: "CBR → CBZ",
 };
 
 interface JobTypeBadgeProps {

apps/backoffice/app/globals.css

@@ -248,6 +248,29 @@ body::after {
   overflow: hidden;
 }
 
+/* Reading progress badge variants */
+.badge-unread {
+  background: hsl(var(--color-muted) / 0.6);
+  color: hsl(var(--color-muted-foreground));
+  border-color: hsl(var(--color-border));
+}
+
+.badge-in-progress {
+  background: hsl(38 92% 50% / 0.15);
+  color: hsl(38 92% 40%);
+  border-color: hsl(38 92% 50% / 0.3);
+}
+
+.dark .badge-in-progress {
+  color: hsl(38 92% 65%);
+}
+
+.badge-completed {
+  background: hsl(var(--color-success) / 0.15);
+  color: hsl(var(--color-success));
+  border-color: hsl(var(--color-success) / 0.3);
+}
+
 /* Hide scrollbar */
 .scrollbar-hide {
   -ms-overflow-style: none;

apps/backoffice/app/jobs/[id]/page.tsx

@@ -1,9 +1,9 @@
 import { notFound } from "next/navigation";
 import Link from "next/link";
 import { apiFetch } from "../../../lib/api";
-import { 
+import {
   Card, CardHeader, CardTitle, CardDescription, CardContent,
-  StatusBadge, JobTypeBadge, StatBox, ProgressBar 
+  StatusBadge, JobTypeBadge, StatBox, ProgressBar
 } from "../../components/ui";
 
 interface JobDetailPageProps {
@@ -13,11 +13,13 @@ interface JobDetailPageProps {
 interface JobDetails {
   id: string;
   library_id: string | null;
+  book_id: string | null;
   type: string;
   status: string;
   created_at: string;
   started_at: string | null;
   finished_at: string | null;
+  phase2_started_at: string | null;
   current_file: string | null;
   progress_percent: number | null;
   processed_files: number | null;
@@ -38,6 +40,34 @@ interface JobError {
   created_at: string;
 }
 
+const JOB_TYPE_INFO: Record<string, { label: string; description: string; isThumbnailOnly: boolean }> = {
+  rebuild: {
+    label: "Incremental index",
+    description: "Scans for new/modified files, analyzes them and generates missing thumbnails.",
+    isThumbnailOnly: false,
+  },
+  full_rebuild: {
+    label: "Full re-index",
+    description: "Clears all existing data then performs a complete re-scan, re-analysis and thumbnail generation.",
+    isThumbnailOnly: false,
+  },
+  thumbnail_rebuild: {
+    label: "Thumbnail rebuild",
+    description: "Generates thumbnails only for books that are missing one. Existing thumbnails are preserved.",
+    isThumbnailOnly: true,
+  },
+  thumbnail_regenerate: {
+    label: "Thumbnail regeneration",
+    description: "Regenerates all thumbnails from scratch, replacing existing ones.",
+    isThumbnailOnly: true,
+  },
+  cbr_to_cbz: {
+    label: "CBR → CBZ conversion",
+    description: "Converts a CBR archive to the open CBZ format.",
+    isThumbnailOnly: false,
+  },
+};
+
 async function getJobDetails(jobId: string): Promise<JobDetails | null> {
   try {
     return await apiFetch<JobDetails>(`/index/jobs/${jobId}`);
@@ -58,16 +88,15 @@ function formatDuration(start: string, end: string | null): string {
   const startDate = new Date(start);
   const endDate = end ? new Date(end) : new Date();
   const diff = endDate.getTime() - startDate.getTime();
-  
+
   if (diff < 60000) return `${Math.floor(diff / 1000)}s`;
   if (diff < 3600000) return `${Math.floor(diff / 60000)}m ${Math.floor((diff % 60000) / 1000)}s`;
   return `${Math.floor(diff / 3600000)}h ${Math.floor((diff % 3600000) / 60000)}m`;
 }
 
-function formatSpeed(stats: { scanned_files: number } | null, duration: number): string {
-  if (!stats || duration === 0) return "-";
-  const filesPerSecond = stats.scanned_files / (duration / 1000);
-  return `${filesPerSecond.toFixed(1)} f/s`;
+function formatSpeed(count: number, durationMs: number): string {
+  if (durationMs === 0 || count === 0) return "-";
+  return `${(count / (durationMs / 1000)).toFixed(1)}/s`;
 }
 
 export default async function JobDetailPage({ params }: JobDetailPageProps) {
@@ -81,15 +110,49 @@ export default async function JobDetailPage({ params }: JobDetailPageProps) {
     notFound();
   }
 
-  const duration = job.started_at 
+  const typeInfo = JOB_TYPE_INFO[job.type] ?? {
+    label: job.type,
+    description: null,
+    isThumbnailOnly: false,
+  };
+
+  const durationMs = job.started_at
     ? new Date(job.finished_at || new Date()).getTime() - new Date(job.started_at).getTime()
     : 0;
 
+  const isCompleted = job.status === "success";
+  const isFailed = job.status === "failed";
+  const isCancelled = job.status === "cancelled";
+  const isThumbnailPhase = job.status === "generating_thumbnails";
+  const { isThumbnailOnly } = typeInfo;
+
+  // Which label to use for the progress card
+  const progressTitle = isThumbnailOnly
+    ? "Thumbnails"
+    : isThumbnailPhase
+      ? "Phase 2 — Thumbnails"
+      : "Phase 1 — Discovery";
+
+  const progressDescription = isThumbnailOnly
+    ? undefined
+    : isThumbnailPhase
+      ? "Generating thumbnails for the analyzed books"
+      : "Scanning and indexing files in the library";
+
+  // Speed metric: thumbnail count for thumbnail jobs, scanned files for index jobs
+  const speedCount = isThumbnailOnly
+    ? (job.processed_files ?? 0)
+    : (job.stats_json?.scanned_files ?? 0);
+
+  const showProgressCard =
+    (isCompleted || isFailed || job.status === "running" || isThumbnailPhase) &&
+    (job.total_files != null || !!job.current_file);
+
   return (
     <>
       <div className="mb-6">
-        <Link 
-          href="/jobs" 
+        <Link
+          href="/jobs"
           className="inline-flex items-center text-sm text-muted-foreground hover:text-primary transition-colors duration-200"
         >
           <svg className="w-4 h-4 mr-1" fill="none" stroke="currentColor" viewBox="0 0 24 24">
@@ -100,11 +163,72 @@ export default async function JobDetailPage({ params }: JobDetailPageProps) {
         <h1 className="text-3xl font-bold text-foreground mt-2">Job Details</h1>
       </div>
 
+      {/* Summary banner — completed */}
+      {isCompleted && job.started_at && (
+        <div className="mb-6 p-4 rounded-xl bg-success/10 border border-success/30 flex items-start gap-3">
+          <svg className="w-5 h-5 text-success mt-0.5 shrink-0" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+            <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M9 12l2 2 4-4m6 2a9 9 0 11-18 0 9 9 0 0118 0z" />
+          </svg>
+          <div className="text-sm text-success">
+            <span className="font-semibold">Completed in {formatDuration(job.started_at, job.finished_at)}</span>
+            {job.stats_json && (
+              <span className="ml-2 text-success/80">
+                — {job.stats_json.scanned_files} scanned, {job.stats_json.indexed_files} indexed
+                {job.stats_json.removed_files > 0 && `, ${job.stats_json.removed_files} removed`}
+                {job.stats_json.errors > 0 && `, ${job.stats_json.errors} errors`}
+                {job.total_files != null && job.total_files > 0 && `, ${job.total_files} thumbnails`}
+              </span>
+            )}
+            {!job.stats_json && isThumbnailOnly && job.total_files != null && (
+              <span className="ml-2 text-success/80">
+                — {job.processed_files ?? job.total_files} thumbnails generated
+              </span>
+            )}
+          </div>
+        </div>
+      )}
+
+      {/* Summary banner — failed */}
+      {isFailed && (
+        <div className="mb-6 p-4 rounded-xl bg-destructive/10 border border-destructive/30 flex items-start gap-3">
+          <svg className="w-5 h-5 text-destructive mt-0.5 shrink-0" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+            <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M12 8v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" />
+          </svg>
+          <div className="text-sm text-destructive">
+            <span className="font-semibold">Job failed</span>
+            {job.started_at && (
+              <span className="ml-2 text-destructive/80">after {formatDuration(job.started_at, job.finished_at)}</span>
+            )}
+            {job.error_opt && (
+              <p className="mt-1 text-destructive/70 font-mono text-xs break-all">{job.error_opt}</p>
+            )}
+          </div>
+        </div>
+      )}
+
+      {/* Summary banner — cancelled */}
+      {isCancelled && (
+        <div className="mb-6 p-4 rounded-xl bg-muted border border-border flex items-start gap-3">
+          <svg className="w-5 h-5 text-muted-foreground mt-0.5 shrink-0" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+            <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M18.364 18.364A9 9 0 005.636 5.636m12.728 12.728A9 9 0 015.636 5.636m12.728 12.728L5.636 5.636" />
+          </svg>
+          <span className="text-sm text-muted-foreground">
+            <span className="font-semibold">Cancelled</span>
+            {job.started_at && (
+              <span className="ml-2">after {formatDuration(job.started_at, job.finished_at)}</span>
+            )}
+          </span>
+        </div>
+      )}
+
       <div className="grid grid-cols-1 lg:grid-cols-2 gap-6">
         {/* Overview Card */}
         <Card>
           <CardHeader>
             <CardTitle>Overview</CardTitle>
+            {typeInfo.description && (
+              <CardDescription>{typeInfo.description}</CardDescription>
+            )}
           </CardHeader>
           <CardContent className="space-y-3">
             <div className="flex items-center justify-between py-2 border-b border-border/60">
@@ -113,16 +237,38 @@ export default async function JobDetailPage({ params }: JobDetailPageProps) {
             </div>
             <div className="flex items-center justify-between py-2 border-b border-border/60">
               <span className="text-sm text-muted-foreground">Type</span>
-              <JobTypeBadge type={job.type} />
+              <div className="flex items-center gap-2">
+                <JobTypeBadge type={job.type} />
+                <span className="text-sm text-muted-foreground">{typeInfo.label}</span>
+              </div>
             </div>
             <div className="flex items-center justify-between py-2 border-b border-border/60">
               <span className="text-sm text-muted-foreground">Status</span>
               <StatusBadge status={job.status} />
             </div>
-            <div className="flex items-center justify-between py-2">
+            <div className={`flex items-center justify-between py-2 ${(job.book_id || job.started_at) ? "border-b border-border/60" : ""}`}>
               <span className="text-sm text-muted-foreground">Library</span>
               <span className="text-sm text-foreground">{job.library_id || "All libraries"}</span>
             </div>
+            {job.book_id && (
+              <div className={`flex items-center justify-between py-2 ${job.started_at ? "border-b border-border/60" : ""}`}>
+                <span className="text-sm text-muted-foreground">Book</span>
+                <Link
+                  href={`/books/${job.book_id}`}
+                  className="text-sm text-primary hover:text-primary/80 font-mono hover:underline"
+                >
+                  {job.book_id.slice(0, 8)}…
+                </Link>
+              </div>
+            )}
+            {job.started_at && (
+              <div className="flex items-center justify-between py-2">
+                <span className="text-sm text-muted-foreground">Duration</span>
+                <span className="text-sm font-semibold text-foreground">
+                  {formatDuration(job.started_at, job.finished_at)}
+                </span>
+              </div>
+            )}
           </CardContent>
         </Card>
 
@@ -131,101 +277,194 @@ export default async function JobDetailPage({ params }: JobDetailPageProps) {
           <CardHeader>
             <CardTitle>Timeline</CardTitle>
           </CardHeader>
-          <CardContent className="space-y-4">
-            <div className="flex items-start gap-4">
-              <div className={`w-2 h-2 rounded-full mt-2 ${job.created_at ? 'bg-success' : 'bg-muted'}`} />
-              <div className="flex-1">
-                <span className="text-sm font-medium text-foreground">Created</span>
-                <p className="text-sm text-muted-foreground">{new Date(job.created_at).toLocaleString()}</p>
+          <CardContent>
+            <div className="relative">
+              {/* Vertical line */}
+              <div className="absolute left-[7px] top-2 bottom-2 w-px bg-border" />
+
+              <div className="space-y-5">
+                {/* Created */}
+                <div className="flex items-start gap-4">
+                  <div className="w-3.5 h-3.5 rounded-full mt-0.5 bg-muted border-2 border-border shrink-0 z-10" />
+                  <div className="flex-1 min-w-0">
+                    <span className="text-sm font-medium text-foreground">Created</span>
+                    <p className="text-xs text-muted-foreground">{new Date(job.created_at).toLocaleString()}</p>
+                  </div>
+                </div>
+
+                {/* Phase 1 start — for index jobs that have two phases */}
+                {job.started_at && job.phase2_started_at && (
+                  <div className="flex items-start gap-4">
+                    <div className="w-3.5 h-3.5 rounded-full mt-0.5 bg-primary shrink-0 z-10" />
+                    <div className="flex-1 min-w-0">
+                      <span className="text-sm font-medium text-foreground">Phase 1 — Discovery</span>
+                      <p className="text-xs text-muted-foreground">{new Date(job.started_at).toLocaleString()}</p>
+                      <p className="text-xs text-primary/80 font-medium mt-0.5">
+                        Duration: {formatDuration(job.started_at, job.phase2_started_at)}
+                        {job.stats_json && (
+                          <span className="text-muted-foreground font-normal ml-1">
+                            · {job.stats_json.scanned_files} scanned, {job.stats_json.indexed_files} indexed
+                            {job.stats_json.removed_files > 0 && `, ${job.stats_json.removed_files} removed`}
+                          </span>
+                        )}
+                      </p>
+                    </div>
+                  </div>
+                )}
+
+                {/* Phase 2 start — for index jobs that have two phases */}
+                {job.phase2_started_at && (
+                  <div className="flex items-start gap-4">
+                    <div className={`w-3.5 h-3.5 rounded-full mt-0.5 shrink-0 z-10 ${
+                      job.finished_at ? "bg-primary" : "bg-primary animate-pulse"
+                    }`} />
+                    <div className="flex-1 min-w-0">
+                      <span className="text-sm font-medium text-foreground">
+                        {isThumbnailOnly ? "Thumbnails" : "Phase 2 — Thumbnails"}
+                      </span>
+                      <p className="text-xs text-muted-foreground">{new Date(job.phase2_started_at).toLocaleString()}</p>
+                      {job.finished_at && (
+                        <p className="text-xs text-primary/80 font-medium mt-0.5">
+                          Duration: {formatDuration(job.phase2_started_at, job.finished_at)}
+                          {job.total_files != null && job.total_files > 0 && (
+                            <span className="text-muted-foreground font-normal ml-1">
+                              · {job.processed_files ?? job.total_files} thumbnails
+                            </span>
+                          )}
+                        </p>
+                      )}
+                    </div>
+                  </div>
+                )}
+
+                {/* Started — for jobs without phase2 (cbr_to_cbz, or no phase yet) */}
+                {job.started_at && !job.phase2_started_at && (
+                  <div className="flex items-start gap-4">
+                    <div className={`w-3.5 h-3.5 rounded-full mt-0.5 shrink-0 z-10 ${
+                      job.finished_at ? "bg-primary" : "bg-primary animate-pulse"
+                    }`} />
+                    <div className="flex-1 min-w-0">
+                      <span className="text-sm font-medium text-foreground">Started</span>
+                      <p className="text-xs text-muted-foreground">{new Date(job.started_at).toLocaleString()}</p>
+                    </div>
+                  </div>
+                )}
+
+                {/* Pending — not started yet */}
+                {!job.started_at && (
+                  <div className="flex items-start gap-4">
+                    <div className="w-3.5 h-3.5 rounded-full mt-0.5 bg-warning shrink-0 z-10" />
+                    <div className="flex-1 min-w-0">
+                      <span className="text-sm font-medium text-foreground">Waiting to start…</span>
+                    </div>
+                  </div>
+                )}
+
+                {/* Finished */}
+                {job.finished_at && (
+                  <div className="flex items-start gap-4">
+                    <div className={`w-3.5 h-3.5 rounded-full mt-0.5 shrink-0 z-10 ${
+                      isCompleted ? "bg-success" : isFailed ? "bg-destructive" : "bg-muted"
+                    }`} />
+                    <div className="flex-1 min-w-0">
+                      <span className="text-sm font-medium text-foreground">
+                        {isCompleted ? "Completed" : isFailed ? "Failed" : "Cancelled"}
+                      </span>
+                      <p className="text-xs text-muted-foreground">{new Date(job.finished_at).toLocaleString()}</p>
+                    </div>
+                  </div>
+                )}
               </div>
             </div>
-            <div className="flex items-start gap-4">
-              <div className={`w-2 h-2 rounded-full mt-2 ${job.started_at ? 'bg-success' : job.created_at ? 'bg-warning' : 'bg-muted'}`} />
-              <div className="flex-1">
-                <span className="text-sm font-medium text-foreground">Started</span>
-                <p className="text-sm text-muted-foreground">
-                  {job.started_at ? new Date(job.started_at).toLocaleString() : "Pending..."}
-                </p>
-              </div>
-            </div>
-            <div className="flex items-start gap-4">
-              <div className={`w-2 h-2 rounded-full mt-2 ${job.finished_at ? 'bg-success' : job.started_at ? 'bg-primary animate-pulse' : 'bg-muted'}`} />
-              <div className="flex-1">
-                <span className="text-sm font-medium text-foreground">Finished</span>
-                <p className="text-sm text-muted-foreground">
-                  {job.finished_at 
-                    ? new Date(job.finished_at).toLocaleString()
-                    : job.started_at 
-                      ? "Running..."
-                      : "Waiting..."
-                  }
-                </p>
-              </div>
-            </div>
-            {job.started_at && (
-              <div className="mt-4 inline-flex items-center px-3 py-1.5 bg-primary/10 text-primary rounded-lg text-sm font-medium">
-                Duration: {formatDuration(job.started_at, job.finished_at)}
-              </div>
-            )}
           </CardContent>
         </Card>
 
         {/* Progress Card */}
-        {(job.status === "running" || job.status === "generating_thumbnails" || job.status === "success" || job.status === "failed") && (
+        {showProgressCard && (
           <Card>
             <CardHeader>
-              <CardTitle>{job.status === "generating_thumbnails" ? "Thumbnails" : "Progress"}</CardTitle>
+              <CardTitle>{progressTitle}</CardTitle>
+              {progressDescription && <CardDescription>{progressDescription}</CardDescription>}
             </CardHeader>
             <CardContent>
               {job.total_files != null && job.total_files > 0 && (
                 <>
                   <ProgressBar value={job.progress_percent || 0} showLabel size="lg" className="mb-4" />
                   <div className="grid grid-cols-3 gap-4">
-                    <StatBox value={job.processed_files ?? 0} label="Processed" variant="primary" />
-                    <StatBox value={job.total_files} label={job.status === "generating_thumbnails" ? "Total thumbnails" : "Total"} />
-                    <StatBox value={job.total_files - (job.processed_files ?? 0)} label="Remaining" variant="warning" />
+                    <StatBox
+                      value={job.processed_files ?? 0}
+                      label={isThumbnailOnly || isThumbnailPhase ? "Generated" : "Processed"}
+                      variant="primary"
+                    />
+                    <StatBox value={job.total_files} label="Total" />
+                    <StatBox
+                      value={Math.max(0, job.total_files - (job.processed_files ?? 0))}
+                      label="Remaining"
+                      variant={isCompleted ? "default" : "warning"}
+                    />
                   </div>
                 </>
               )}
               {job.current_file && (
                 <div className="mt-4 p-3 bg-muted/50 rounded-lg">
-                  <span className="text-sm text-muted-foreground">Current file:</span>
-                  <code className="block mt-1 text-xs font-mono text-foreground truncate">{job.current_file}</code>
+                  <span className="text-xs text-muted-foreground uppercase tracking-wide">Current file</span>
+                  <code className="block mt-1 text-xs font-mono text-foreground break-all">{job.current_file}</code>
                 </div>
               )}
             </CardContent>
           </Card>
         )}
 
-        {/* Statistics Card */}
-        {job.stats_json && (
+        {/* Index Statistics — index jobs only */}
+        {job.stats_json && !isThumbnailOnly && (
           <Card>
             <CardHeader>
-              <CardTitle>Statistics</CardTitle>
+              <CardTitle>Index statistics</CardTitle>
+              {job.started_at && (
+                <CardDescription>
+                  {formatDuration(job.started_at, job.finished_at)}
+                  {speedCount > 0 && ` · ${formatSpeed(speedCount, durationMs)} scan rate`}
+                </CardDescription>
+              )}
             </CardHeader>
             <CardContent>
-              <div className="grid grid-cols-2 sm:grid-cols-4 gap-4 mb-4">
+              <div className="grid grid-cols-2 sm:grid-cols-4 gap-4">
                 <StatBox value={job.stats_json.scanned_files} label="Scanned" variant="success" />
                 <StatBox value={job.stats_json.indexed_files} label="Indexed" variant="primary" />
                 <StatBox value={job.stats_json.removed_files} label="Removed" variant="warning" />
                 <StatBox value={job.stats_json.errors} label="Errors" variant={job.stats_json.errors > 0 ? "error" : "default"} />
               </div>
-              {job.started_at && (
-                <div className="flex items-center justify-between py-2 border-t border-border/60">
-                  <span className="text-sm text-muted-foreground">Speed:</span>
-                  <span className="text-sm font-medium text-foreground">{formatSpeed(job.stats_json, duration)}</span>
-                </div>
-              )}
             </CardContent>
           </Card>
         )}
 
-        {/* Errors Card */}
+        {/* Thumbnail statistics — thumbnail-only jobs, completed */}
+        {isThumbnailOnly && isCompleted && job.total_files != null && (
+          <Card>
+            <CardHeader>
+              <CardTitle>Thumbnail statistics</CardTitle>
+              {job.started_at && (
+                <CardDescription>
+                  {formatDuration(job.started_at, job.finished_at)}
+                  {speedCount > 0 && ` · ${formatSpeed(speedCount, durationMs)} thumbnails/s`}
+                </CardDescription>
+              )}
+            </CardHeader>
+            <CardContent>
+              <div className="grid grid-cols-2 gap-4">
+                <StatBox value={job.processed_files ?? job.total_files} label="Generated" variant="success" />
+                <StatBox value={job.total_files} label="Total" />
+              </div>
+            </CardContent>
+          </Card>
+        )}
+
+        {/* File errors */}
         {errors.length > 0 && (
           <Card className="lg:col-span-2">
             <CardHeader>
-              <CardTitle>Errors ({errors.length})</CardTitle>
-              <CardDescription>Errors encountered during job execution</CardDescription>
+              <CardTitle>File errors ({errors.length})</CardTitle>
+              <CardDescription>Errors encountered while processing individual files</CardDescription>
             </CardHeader>
             <CardContent className="space-y-2 max-h-80 overflow-y-auto">
               {errors.map((error) => (
@@ -238,19 +477,6 @@ export default async function JobDetailPage({ params }: JobDetailPageProps) {
             </CardContent>
           </Card>
         )}
-
-        {/* Error Message */}
-        {job.error_opt && (
-          <Card className="lg:col-span-2">
-            <CardHeader>
-              <CardTitle>Error</CardTitle>
-              <CardDescription>Job failed with error</CardDescription>
-            </CardHeader>
-            <CardContent>
-              <pre className="p-4 bg-destructive/10 rounded-lg text-sm text-destructive overflow-x-auto border border-destructive/20">{job.error_opt}</pre>
-            </CardContent>
-          </Card>
-        )}
       </div>
     </>
   );

apps/backoffice/app/layout.tsx

@@ -7,6 +7,7 @@ import { ThemeProvider } from "./theme-provider";
 import { ThemeToggle } from "./theme-toggle";
 import { JobsIndicator } from "./components/JobsIndicator";
 import { NavIcon, Icon } from "./components/ui";
+import { MobileNav } from "./components/MobileNav";
 
 export const metadata: Metadata = {
   title: "StripStream Backoffice",
@@ -61,17 +62,17 @@ export default function RootLayout({ children }: { children: ReactNode }) {
               <div className="flex items-center gap-2">
                 <div className="hidden md:flex items-center gap-1">
                   {navItems.map((item) => (
-                    <NavLink key={item.href} href={item.href}>
-                      <NavIcon name={item.icon} /> 
-                      <span className="ml-2">{item.label}</span>
+                    <NavLink key={item.href} href={item.href} title={item.label}>
+                      <NavIcon name={item.icon} />
+                      <span className="ml-2 hidden lg:inline">{item.label}</span>
                     </NavLink>
                   ))}
                 </div>
-                
+
                 {/* Actions */}
                 <div className="flex items-center gap-1 pl-4 ml-2 border-l border-border/60">
                   <JobsIndicator />
-                  <Link 
+                  <Link
                     href="/settings"
                     className="p-2 rounded-lg text-muted-foreground hover:text-foreground hover:bg-accent transition-colors"
                     title="Settings"
@@ -79,6 +80,7 @@ export default function RootLayout({ children }: { children: ReactNode }) {
                     <Icon name="settings" size="md" />
                   </Link>
                   <ThemeToggle />
+                  <MobileNav navItems={navItems} />
                 </div>
               </div>
             </nav>
@@ -95,18 +97,19 @@ export default function RootLayout({ children }: { children: ReactNode }) {
 }
 
 // Navigation Link Component
-function NavLink({ href, children }: { href: NavItem["href"]; children: React.ReactNode }) {
+function NavLink({ href, title, children }: { href: NavItem["href"]; title?: string; children: React.ReactNode }) {
   return (
-    <Link 
+    <Link
       href={href}
+      title={title}
       className="
-        flex items-center 
-        px-3 py-2 
-        rounded-lg 
-        text-sm font-medium 
-        text-muted-foreground 
-        hover:text-foreground 
-        hover:bg-accent 
+        flex items-center
+        px-2 lg:px-3 py-2
+        rounded-lg
+        text-sm font-medium
+        text-muted-foreground
+        hover:text-foreground
+        hover:bg-accent
         transition-colors duration-200
         active:scale-[0.98]
       "

apps/backoffice/app/settings/SettingsPage.tsx

@@ -247,7 +247,7 @@ export default function SettingsPage({ initialSettings, initialCacheStats, initi
             <Icon name="performance" size="md" />
             Performance Limits
           </CardTitle>
-          <CardDescription>Configure API performance and rate limiting</CardDescription>
+          <CardDescription>Configure API performance, rate limiting, and thumbnail generation concurrency</CardDescription>
         </CardHeader>
         <CardContent>
           <div className="space-y-4">
@@ -266,6 +266,9 @@ export default function SettingsPage({ initialSettings, initialCacheStats, initi
                   }}
                   onBlur={() => handleUpdateSetting("limits", settings.limits)}
                 />
+                <p className="text-xs text-muted-foreground mt-1">
+                  Maximum number of page renders and thumbnail generations running in parallel
+                </p>
               </FormField>
               <FormField className="flex-1">
                 <label className="text-sm font-medium text-muted-foreground mb-1 block">Timeout (seconds)</label>
@@ -299,7 +302,7 @@ export default function SettingsPage({ initialSettings, initialCacheStats, initi
               </FormField>
             </FormRow>
             <p className="text-sm text-muted-foreground">
-              Note: Changes to limits require a server restart to take effect.
+              Note: Changes to limits require a server restart to take effect. The "Concurrent Renders" setting controls both page rendering and thumbnail generation parallelism.
             </p>
           </div>
         </CardContent>
@@ -424,7 +427,7 @@ export default function SettingsPage({ initialSettings, initialCacheStats, initi
             </div>
 
             <p className="text-sm text-muted-foreground">
-              Note: Thumbnail settings are used during indexing. Existing thumbnails will not be regenerated automatically.
+              Note: Thumbnail settings are used during indexing. Existing thumbnails will not be regenerated automatically. The concurrency for thumbnail generation is controlled by the "Concurrent Renders" setting in Performance Limits above.
             </p>
           </div>
         </CardContent>

apps/backoffice/lib/api.ts

@@ -13,6 +13,7 @@ export type LibraryDto = {
 export type IndexJobDto = {
   id: string;
   library_id: string | null;
+  book_id: string | null;
   type: string;
   status: string;
   started_at: string | null;
@@ -45,6 +46,14 @@ export type FolderItem = {
   has_children: boolean;
 };
 
+export type ReadingStatus = "unread" | "reading" | "read";
+
+export type ReadingProgressDto = {
+  status: ReadingStatus;
+  current_page: number | null;
+  last_read_at: string | null;
+};
+
 export type BookDto = {
   id: string;
   library_id: string;
@@ -59,6 +68,10 @@ export type BookDto = {
   file_format: string | null;
   file_parse_status: string | null;
   updated_at: string;
+  // Présents uniquement sur GET /books/:id (pas dans la liste)
+  reading_status?: ReadingStatus;
+  reading_current_page?: number | null;
+  reading_last_read_at?: string | null;
 };
 
 export type BooksPageDto = {
@@ -89,8 +102,8 @@ export type SeriesDto = {
   first_book_id: string;
 };
 
-function config() {
-  const baseUrl = process.env.API_BASE_URL || "http://api:8080";
+export function config() {
+  const baseUrl = process.env.API_BASE_URL || "http://api:7080";
   const token = process.env.API_BOOTSTRAP_TOKEN;
   if (!token) {
     throw new Error("API_BOOTSTRAP_TOKEN is required for backoffice");
@@ -348,3 +361,22 @@ export async function clearCache() {
 export async function getThumbnailStats() {
   return apiFetch<ThumbnailStats>("/settings/thumbnail/stats");
 }
+
+export async function convertBook(bookId: string) {
+  return apiFetch<IndexJobDto>(`/books/${bookId}/convert`, { method: "POST" });
+}
+
+export async function fetchReadingProgress(bookId: string) {
+  return apiFetch<ReadingProgressDto>(`/books/${bookId}/progress`);
+}
+
+export async function updateReadingProgress(
+  bookId: string,
+  status: ReadingStatus,
+  currentPage?: number,
+) {
+  return apiFetch<ReadingProgressDto>(`/books/${bookId}/progress`, {
+    method: "PATCH",
+    body: JSON.stringify({ status, current_page: currentPage ?? null }),
+  });
+}

apps/backoffice/tsconfig.json

@@ -21,7 +21,10 @@
       {
         "name": "next"
       }
-    ]
+    ],
+    "paths": {
+      "@/*": ["./*"]
+    }
   },
   "include": [
     "next-env.d.ts",

apps/indexer/AGENTS.md

@@ -0,0 +1,104 @@
+# apps/indexer — Service d'indexation
+
+Service background sur le port **7081**. Voir `AGENTS.md` racine pour les conventions globales.
+
+## Structure des fichiers
+
+| Fichier | Rôle |
+|---------|------|
+| `main.rs` | Point d'entrée, initialisation, lancement du worker |
+| `lib.rs` | `AppState` (pool, meili_url, meili_master_key) |
+| `worker.rs` | Boucle principale : claim job → process → cleanup stale |
+| `job.rs` | `claim_next_job`, `process_job`, `fail_job`, `cleanup_stale_jobs` |
+| `scanner.rs` | Phase 1 discovery : WalkDir + `parse_metadata_fast` (zéro I/O archive), skip dossiers inchangés via mtime, batching DB |
+| `analyzer.rs` | Phase 2 analysis : ouvre chaque archive une fois (`analyze_book`), génère page_count + thumbnail WebP |
+| `batch.rs` | `flush_all_batches` avec UNNEST, structures `BookInsert/Update/FileInsert/Update/ErrorInsert` |
+| `scheduler.rs` | Auto-scan : vérifie toutes les 60s les bibliothèques à monitorer |
+| `watcher.rs` | File watcher temps réel |
+| `meili.rs` | Indexation/sync Meilisearch |
+| `api.rs` | Endpoints HTTP de l'indexer (/health, /ready) |
+| `utils.rs` | `remap_libraries_path`, `unmap_libraries_path`, `compute_fingerprint`, `kind_from_format` |
+
+## Cycle de vie d'un job
+
+```
+claim_next_job (UPDATE ... RETURNING, status pending→running)
+  └─ process_job
+       ├─ Phase 1 : scanner::scan_library_discovery
+       │    ├─ WalkDir + parse_metadata_fast (zéro I/O archive)
+       │    ├─ skip dossiers via directory_mtimes (table DB)
+       │    └─ INSERT books (page_count=NULL) → livres visibles immédiatement
+       ├─ meili::sync_meili
+       ├─ analyzer::cleanup_orphaned_thumbnails (full_rebuild uniquement)
+       └─ Phase 2 : analyzer::analyze_library_books
+            ├─ SELECT books WHERE page_count IS NULL
+            ├─ parsers::analyze_book → (page_count, first_page_bytes)
+            ├─ generate_thumbnail (WebP, Lanczos3)
+            └─ UPDATE books SET page_count, thumbnail_path
+
+Jobs spéciaux :
+  thumbnail_rebuild   → analyze_library_books(thumbnail_only=true)
+  thumbnail_regenerate → regenerate_thumbnails (clear + re-analyze)
+```
+
+- Annulation : `is_job_cancelled` vérifié toutes les 10 fichiers ou 1s — retourne `Err("Job cancelled")`
+- Jobs stale (running au redémarrage) → nettoyés par `cleanup_stale_jobs` au boot
+
+## Pattern batch (batch.rs)
+
+Toutes les opérations DB massives passent par `flush_all_batches` avec UNNEST :
+
+```rust
+// Accumuler dans des Vec<BookInsert>, Vec<FileInsert>, etc.
+books_to_insert.push(BookInsert { ... });
+
+// Flush quand plein ou en fin de scan
+if books_to_insert.len() >= BATCH_SIZE {
+    flush_all_batches(&pool, &mut books_update, &mut files_update,
+                      &mut books_insert, &mut files_insert, &mut errors_insert).await?;
+}
+```
+
+Toutes les opérations du flush sont dans une seule transaction.
+
+## Scan filesystem — architecture 2 phases
+
+### Phase 1 : Discovery (`scanner.rs`)
+
+Pipeline allégé — **zéro ouverture d'archive** :
+1. Charger `directory_mtimes` depuis la DB
+2. WalkDir : pour chaque dossier, comparer mtime filesystem vs mtime stocké → skip si inchangé
+3. Pour chaque fichier : `parse_metadata_fast` (title/series/volume depuis filename uniquement)
+4. INSERT/UPDATE avec `page_count = NULL` — les livres sont visibles immédiatement
+5. Upsert `directory_mtimes` en fin de scan
+
+Fingerprint = SHA256(taille + mtime + filename) pour détecter les changements sans relire le fichier.
+
+### Phase 2 : Analysis (`analyzer.rs`)
+
+Traitement progressif en background :
+- Query `WHERE page_count IS NULL` (ou `thumbnail_path IS NULL` pour thumbnail jobs)
+- Concurrence bornée (`futures::stream::for_each_concurrent`, défaut 4)
+- Par livre : `parsers::analyze_book(path, format)` → `(page_count, first_page_bytes)`
+- Génération thumbnail : resize Lanczos3 + encode WebP
+- UPDATE `books SET page_count, thumbnail_path`
+- Config lue depuis `app_settings` (clés `'thumbnail'` et `'limits'`)
+
+## Path remapping
+
+```rust
+// abs_path en DB = chemin conteneur (/libraries/...)
+// Sur l'hôte : LIBRARIES_ROOT_PATH remplace /libraries
+utils::remap_libraries_path(&abs_path)    // DB → filesystem local
+utils::unmap_libraries_path(&local_path) // filesystem local → DB
+```
+
+## Gotchas
+
+- **Thumbnails** : générés **directement par l'indexer** (phase 2, `analyzer.rs`). L'API ne gère plus la génération — elle crée juste les jobs en DB.
+- **page_count = NULL** : après la phase discovery, tous les nouveaux livres ont `page_count = NULL`. La phase analysis les remplit progressivement. Ne pas confondre avec une erreur.
+- **directory_mtimes** : table DB qui stocke le mtime de chaque dossier scanné. Vidée au full_rebuild, mise à jour après chaque scan. Permet de skipper les dossiers inchangés en scan incrémental.
+- **full_rebuild** : supprime toutes les données puis re-insère. Ignore les fingerprints et les directory_mtimes.
+- **Annulation** : vérifier `is_job_cancelled` régulièrement pour respecter les annulations utilisateur.
+- **Watcher + scheduler** : tournent en tâches tokio séparées dans `worker.rs`, en parallèle de la boucle principale.
+- **spawn_blocking** : l'ouverture d'archive (`analyze_book`) et la génération de thumbnail sont des opérations bloquantes — toujours les wrapper dans `tokio::task::spawn_blocking`.

apps/indexer/Cargo.toml

@@ -4,10 +4,14 @@ version.workspace = true
 edition.workspace = true
 license.workspace = true
 
+[lib]
+
 [dependencies]
 anyhow.workspace = true
 axum.workspace = true
 chrono.workspace = true
+futures = "0.3"
+image.workspace = true
 notify = "6.1"
 parsers = { path = "../../crates/parsers" }
 rand.workspace = true
@@ -23,3 +27,4 @@ tracing.workspace = true
 tracing-subscriber.workspace = true
 uuid.workspace = true
 walkdir.workspace = true
+webp.workspace = true

apps/indexer/Dockerfile

@@ -21,7 +21,11 @@ RUN --mount=type=cache,target=/sccache \
     cargo build --release -p indexer
 
 FROM debian:bookworm-slim
-RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates wget unrar-free && rm -rf /var/lib/apt/lists/*
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    ca-certificates wget \
+    unrar-free unar \
+    poppler-utils \
+    && rm -rf /var/lib/apt/lists/*
 COPY --from=builder /app/target/release/indexer /usr/local/bin/indexer
-EXPOSE 8081
+EXPOSE 7081
 CMD ["/usr/local/bin/indexer"]

apps/indexer/src/analyzer.rs

@@ -0,0 +1,440 @@
+use anyhow::Result;
+use futures::stream::{self, StreamExt};
+use image::GenericImageView;
+use parsers::{analyze_book, BookFormat};
+use sqlx::Row;
+use std::path::Path;
+use std::sync::atomic::{AtomicI32, Ordering};
+use std::sync::Arc;
+use tracing::{info, warn};
+use uuid::Uuid;
+
+use crate::{utils, AppState};
+
+#[derive(Clone)]
+struct ThumbnailConfig {
+    enabled: bool,
+    width: u32,
+    height: u32,
+    quality: u8,
+    directory: String,
+}
+
+async fn load_thumbnail_config(pool: &sqlx::PgPool) -> ThumbnailConfig {
+    let fallback = ThumbnailConfig {
+        enabled: true,
+        width: 300,
+        height: 400,
+        quality: 80,
+        directory: "/data/thumbnails".to_string(),
+    };
+    let row = sqlx::query(r#"SELECT value FROM app_settings WHERE key = 'thumbnail'"#)
+        .fetch_optional(pool)
+        .await;
+
+    match row {
+        Ok(Some(row)) => {
+            let value: serde_json::Value = row.get("value");
+            ThumbnailConfig {
+                enabled: value
+                    .get("enabled")
+                    .and_then(|v| v.as_bool())
+                    .unwrap_or(fallback.enabled),
+                width: value
+                    .get("width")
+                    .and_then(|v| v.as_u64())
+                    .map(|v| v as u32)
+                    .unwrap_or(fallback.width),
+                height: value
+                    .get("height")
+                    .and_then(|v| v.as_u64())
+                    .map(|v| v as u32)
+                    .unwrap_or(fallback.height),
+                quality: value
+                    .get("quality")
+                    .and_then(|v| v.as_u64())
+                    .map(|v| v as u8)
+                    .unwrap_or(fallback.quality),
+                directory: value
+                    .get("directory")
+                    .and_then(|v| v.as_str())
+                    .map(|s| s.to_string())
+                    .unwrap_or_else(|| fallback.directory.clone()),
+            }
+        }
+        _ => fallback,
+    }
+}
+
+async fn load_thumbnail_concurrency(pool: &sqlx::PgPool) -> usize {
+    let default_concurrency = 2;
+    let row = sqlx::query(r#"SELECT value FROM app_settings WHERE key = 'limits'"#)
+        .fetch_optional(pool)
+        .await;
+
+    match row {
+        Ok(Some(row)) => {
+            let value: serde_json::Value = row.get("value");
+            value
+                .get("concurrent_renders")
+                .and_then(|v| v.as_u64())
+                .map(|v| v as usize)
+                .unwrap_or(default_concurrency)
+        }
+        _ => default_concurrency,
+    }
+}
+
+fn generate_thumbnail(image_bytes: &[u8], config: &ThumbnailConfig) -> anyhow::Result<Vec<u8>> {
+    let img = image::load_from_memory(image_bytes)
+        .map_err(|e| anyhow::anyhow!("failed to load image: {}", e))?;
+    let (orig_w, orig_h) = img.dimensions();
+    let ratio_w = config.width as f32 / orig_w as f32;
+    let ratio_h = config.height as f32 / orig_h as f32;
+    let ratio = ratio_w.min(ratio_h);
+    let new_w = (orig_w as f32 * ratio) as u32;
+    let new_h = (orig_h as f32 * ratio) as u32;
+    let resized = img.resize(new_w, new_h, image::imageops::FilterType::Triangle);
+    let rgba = resized.to_rgba8();
+    let (w, h) = rgba.dimensions();
+    let rgb_data: Vec<u8> = rgba.pixels().flat_map(|p| [p[0], p[1], p[2]]).collect();
+    let quality = config.quality as f32;
+    let webp_data = webp::Encoder::new(&rgb_data, webp::PixelLayout::Rgb, w, h).encode(quality);
+    Ok(webp_data.to_vec())
+}
+
+fn save_thumbnail(
+    book_id: Uuid,
+    thumbnail_bytes: &[u8],
+    config: &ThumbnailConfig,
+) -> anyhow::Result<String> {
+    let dir = Path::new(&config.directory);
+    std::fs::create_dir_all(dir)?;
+    let filename = format!("{}.webp", book_id);
+    let path = dir.join(&filename);
+    std::fs::write(&path, thumbnail_bytes)?;
+    Ok(path.to_string_lossy().to_string())
+}
+
+fn book_format_from_str(s: &str) -> Option<BookFormat> {
+    match s {
+        "cbz" => Some(BookFormat::Cbz),
+        "cbr" => Some(BookFormat::Cbr),
+        "pdf" => Some(BookFormat::Pdf),
+        _ => None,
+    }
+}
+
+/// Phase 2 — Analysis: open each unanalyzed archive once, extract page_count + thumbnail.
+/// `thumbnail_only` = true: only process books missing thumbnail (page_count may already be set).
+/// `thumbnail_only` = false: process books missing page_count.
+pub async fn analyze_library_books(
+    state: &AppState,
+    job_id: Uuid,
+    library_id: Option<Uuid>,
+    thumbnail_only: bool,
+) -> Result<()> {
+    let config = load_thumbnail_config(&state.pool).await;
+
+    if !config.enabled {
+        info!("[ANALYZER] Thumbnails disabled, skipping analysis phase");
+        return Ok(());
+    }
+
+    let concurrency = load_thumbnail_concurrency(&state.pool).await;
+
+    // Query books that need analysis
+    let query_filter = if thumbnail_only {
+        "b.thumbnail_path IS NULL"
+    } else {
+        "b.page_count IS NULL"
+    };
+
+    let sql = format!(
+        r#"
+        SELECT b.id AS book_id, bf.abs_path, bf.format
+        FROM books b
+        JOIN book_files bf ON bf.book_id = b.id
+        WHERE (b.library_id = $1 OR $1 IS NULL)
+          AND {}
+        "#,
+        query_filter
+    );
+
+    let rows = sqlx::query(&sql)
+        .bind(library_id)
+        .fetch_all(&state.pool)
+        .await?;
+
+    if rows.is_empty() {
+        info!("[ANALYZER] No books to analyze");
+        return Ok(());
+    }
+
+    let total = rows.len() as i32;
+    info!(
+        "[ANALYZER] Analyzing {} books (thumbnail_only={}, concurrency={})",
+        total, thumbnail_only, concurrency
+    );
+
+    // Update job status
+    let _ = sqlx::query(
+        "UPDATE index_jobs SET status = 'generating_thumbnails', total_files = $2, processed_files = 0, current_file = NULL WHERE id = $1",
+    )
+    .bind(job_id)
+    .bind(total)
+    .execute(&state.pool)
+    .await;
+
+    let processed_count = Arc::new(AtomicI32::new(0));
+
+    struct BookTask {
+        book_id: Uuid,
+        abs_path: String,
+        format: String,
+    }
+
+    let tasks: Vec<BookTask> = rows
+        .into_iter()
+        .map(|row| BookTask {
+            book_id: row.get("book_id"),
+            abs_path: row.get("abs_path"),
+            format: row.get("format"),
+        })
+        .collect();
+
+    stream::iter(tasks)
+        .for_each_concurrent(concurrency, |task| {
+            let processed_count = processed_count.clone();
+            let pool = state.pool.clone();
+            let config = config.clone();
+
+            async move {
+                let local_path = utils::remap_libraries_path(&task.abs_path);
+                let path = Path::new(&local_path);
+
+                let format = match book_format_from_str(&task.format) {
+                    Some(f) => f,
+                    None => {
+                        warn!("[ANALYZER] Unknown format '{}' for book {}", task.format, task.book_id);
+                        return;
+                    }
+                };
+
+                // Run blocking archive I/O on a thread pool
+                let book_id = task.book_id;
+                let path_owned = path.to_path_buf();
+                let analyze_result = tokio::task::spawn_blocking(move || {
+                    analyze_book(&path_owned, format)
+                })
+                .await;
+
+                let (page_count, image_bytes) = match analyze_result {
+                    Ok(Ok(result)) => result,
+                    Ok(Err(e)) => {
+                        warn!("[ANALYZER] analyze_book failed for book {}: {}", book_id, e);
+                        // Mark parse_status = error in book_files
+                        let _ = sqlx::query(
+                            "UPDATE book_files SET parse_status = 'error', parse_error_opt = $2 WHERE book_id = $1",
+                        )
+                        .bind(book_id)
+                        .bind(e.to_string())
+                        .execute(&pool)
+                        .await;
+                        return;
+                    }
+                    Err(e) => {
+                        warn!("[ANALYZER] spawn_blocking error for book {}: {}", book_id, e);
+                        return;
+                    }
+                };
+
+                // Generate thumbnail
+                let thumb_result = tokio::task::spawn_blocking({
+                    let config = config.clone();
+                    move || generate_thumbnail(&image_bytes, &config)
+                })
+                .await;
+
+                let thumb_bytes = match thumb_result {
+                    Ok(Ok(b)) => b,
+                    Ok(Err(e)) => {
+                        warn!("[ANALYZER] thumbnail generation failed for book {}: {}", book_id, e);
+                        // Still update page_count even if thumbnail fails
+                        let _ = sqlx::query(
+                            "UPDATE books SET page_count = $1 WHERE id = $2",
+                        )
+                        .bind(page_count)
+                        .bind(book_id)
+                        .execute(&pool)
+                        .await;
+                        return;
+                    }
+                    Err(e) => {
+                        warn!("[ANALYZER] spawn_blocking thumbnail error for book {}: {}", book_id, e);
+                        return;
+                    }
+                };
+
+                // Save thumbnail file
+                let save_result = {
+                    let config = config.clone();
+                    tokio::task::spawn_blocking(move || save_thumbnail(book_id, &thumb_bytes, &config))
+                        .await
+                };
+
+                let thumb_path = match save_result {
+                    Ok(Ok(p)) => p,
+                    Ok(Err(e)) => {
+                        warn!("[ANALYZER] save_thumbnail failed for book {}: {}", book_id, e);
+                        let _ = sqlx::query("UPDATE books SET page_count = $1 WHERE id = $2")
+                            .bind(page_count)
+                            .bind(book_id)
+                            .execute(&pool)
+                            .await;
+                        return;
+                    }
+                    Err(e) => {
+                        warn!("[ANALYZER] spawn_blocking save error for book {}: {}", book_id, e);
+                        return;
+                    }
+                };
+
+                // Update DB
+                if let Err(e) = sqlx::query(
+                    "UPDATE books SET page_count = $1, thumbnail_path = $2 WHERE id = $3",
+                )
+                .bind(page_count)
+                .bind(&thumb_path)
+                .bind(book_id)
+                .execute(&pool)
+                .await
+                {
+                    warn!("[ANALYZER] DB update failed for book {}: {}", book_id, e);
+                    return;
+                }
+
+                let processed = processed_count.fetch_add(1, Ordering::Relaxed) + 1;
+                let percent = (processed as f64 / total as f64 * 100.0) as i32;
+                let _ = sqlx::query(
+                    "UPDATE index_jobs SET processed_files = $2, progress_percent = $3 WHERE id = $1",
+                )
+                .bind(job_id)
+                .bind(processed)
+                .bind(percent)
+                .execute(&pool)
+                .await;
+            }
+        })
+        .await;
+
+    let final_count = processed_count.load(Ordering::Relaxed);
+    info!(
+        "[ANALYZER] Analysis complete: {}/{} books processed",
+        final_count, total
+    );
+
+    Ok(())
+}
+
+/// Clear thumbnail files and DB references for books in scope, then re-analyze.
+pub async fn regenerate_thumbnails(
+    state: &AppState,
+    job_id: Uuid,
+    library_id: Option<Uuid>,
+) -> Result<()> {
+    let config = load_thumbnail_config(&state.pool).await;
+
+    // Delete thumbnail files for all books in scope
+    let book_ids_to_clear: Vec<Uuid> = sqlx::query_scalar(
+        r#"SELECT id FROM books WHERE (library_id = $1 OR $1 IS NULL) AND thumbnail_path IS NOT NULL"#,
+    )
+    .bind(library_id)
+    .fetch_all(&state.pool)
+    .await
+    .unwrap_or_default();
+
+    let mut deleted_count = 0usize;
+    for book_id in &book_ids_to_clear {
+        let filename = format!("{}.webp", book_id);
+        let thumbnail_path = Path::new(&config.directory).join(&filename);
+        if thumbnail_path.exists() {
+            if let Err(e) = std::fs::remove_file(&thumbnail_path) {
+                warn!(
+                    "[ANALYZER] Failed to delete thumbnail {}: {}",
+                    thumbnail_path.display(),
+                    e
+                );
+            } else {
+                deleted_count += 1;
+            }
+        }
+    }
+    info!(
+        "[ANALYZER] Deleted {} thumbnail files for regeneration",
+        deleted_count
+    );
+
+    // Clear thumbnail_path in DB
+    sqlx::query(
+        r#"UPDATE books SET thumbnail_path = NULL WHERE (library_id = $1 OR $1 IS NULL)"#,
+    )
+    .bind(library_id)
+    .execute(&state.pool)
+    .await?;
+
+    // Re-analyze all books (now thumbnail_path IS NULL for all)
+    analyze_library_books(state, job_id, library_id, true).await
+}
+
+/// Delete orphaned thumbnail files (books deleted in full_rebuild get new UUIDs).
+pub async fn cleanup_orphaned_thumbnails(state: &AppState) -> Result<()> {
+    let config = load_thumbnail_config(&state.pool).await;
+
+    // Load ALL book IDs across all libraries — we need the complete set to avoid
+    // deleting thumbnails that belong to other libraries during a per-library rebuild.
+    let existing_book_ids: std::collections::HashSet<Uuid> = sqlx::query_scalar(
+        r#"SELECT id FROM books"#,
+    )
+    .fetch_all(&state.pool)
+    .await
+    .unwrap_or_default()
+    .into_iter()
+    .collect();
+
+    let thumbnail_dir = Path::new(&config.directory);
+    if !thumbnail_dir.exists() {
+        return Ok(());
+    }
+
+    let mut deleted_count = 0usize;
+    if let Ok(entries) = std::fs::read_dir(thumbnail_dir) {
+        for entry in entries.flatten() {
+            if let Some(file_name) = entry.file_name().to_str() {
+                if file_name.ends_with(".webp") {
+                    if let Some(book_id_str) = file_name.strip_suffix(".webp") {
+                        if let Ok(book_id) = Uuid::parse_str(book_id_str) {
+                            if !existing_book_ids.contains(&book_id) {
+                                if let Err(e) = std::fs::remove_file(entry.path()) {
+                                    warn!(
+                                        "Failed to delete orphaned thumbnail {}: {}",
+                                        entry.path().display(),
+                                        e
+                                    );
+                                } else {
+                                    deleted_count += 1;
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    info!(
+        "[ANALYZER] Deleted {} orphaned thumbnail files",
+        deleted_count
+    );
+    Ok(())
+}

apps/indexer/src/api.rs

@@ -0,0 +1,16 @@
+use axum::{extract::State, http::StatusCode, Json};
+use serde_json;
+
+use crate::AppState;
+
+pub async fn health() -> &'static str {
+    "ok"
+}
+
+pub async fn ready(State(state): State<AppState>) -> Result<Json<serde_json::Value>, StatusCode> {
+    sqlx::query("SELECT 1")
+        .execute(&state.pool)
+        .await
+        .map_err(|_| StatusCode::SERVICE_UNAVAILABLE)?;
+    Ok(Json(serde_json::json!({"status": "ready"})))
+}

apps/indexer/src/batch.rs

@@ -0,0 +1,233 @@
+use anyhow::Result;
+use chrono::{DateTime, Utc};
+use sqlx::PgPool;
+use uuid::Uuid;
+
+// Batched update data structures
+pub struct BookUpdate {
+    pub book_id: Uuid,
+    pub title: String,
+    pub kind: String,
+    pub series: Option<String>,
+    pub volume: Option<i32>,
+    pub page_count: Option<i32>,
+}
+
+pub struct FileUpdate {
+    pub file_id: Uuid,
+    pub format: String,
+    pub size_bytes: i64,
+    pub mtime: DateTime<Utc>,
+    pub fingerprint: String,
+}
+
+pub struct BookInsert {
+    pub book_id: Uuid,
+    pub library_id: Uuid,
+    pub kind: String,
+    pub title: String,
+    pub series: Option<String>,
+    pub volume: Option<i32>,
+    pub page_count: Option<i32>,
+    pub thumbnail_path: Option<String>,
+}
+
+pub struct FileInsert {
+    pub file_id: Uuid,
+    pub book_id: Uuid,
+    pub format: String,
+    pub abs_path: String,
+    pub size_bytes: i64,
+    pub mtime: DateTime<Utc>,
+    pub fingerprint: String,
+    pub parse_status: String,
+    pub parse_error: Option<String>,
+}
+
+pub struct ErrorInsert {
+    pub job_id: Uuid,
+    pub file_path: String,
+    pub error_message: String,
+}
+
+pub async fn flush_all_batches(
+    pool: &PgPool,
+    books_update: &mut Vec<BookUpdate>,
+    files_update: &mut Vec<FileUpdate>,
+    books_insert: &mut Vec<BookInsert>,
+    files_insert: &mut Vec<FileInsert>,
+    errors_insert: &mut Vec<ErrorInsert>,
+) -> Result<()> {
+    if books_update.is_empty() && files_update.is_empty() && books_insert.is_empty() && files_insert.is_empty() && errors_insert.is_empty() {
+        return Ok(());
+    }
+    
+    let start = std::time::Instant::now();
+    let mut tx = pool.begin().await?;
+    
+    // Batch update books using UNNEST
+    if !books_update.is_empty() {
+        let book_ids: Vec<Uuid> = books_update.iter().map(|b| b.book_id).collect();
+        let titles: Vec<String> = books_update.iter().map(|b| b.title.clone()).collect();
+        let kinds: Vec<String> = books_update.iter().map(|b| b.kind.clone()).collect();
+        let series: Vec<Option<String>> = books_update.iter().map(|b| b.series.clone()).collect();
+        let volumes: Vec<Option<i32>> = books_update.iter().map(|b| b.volume).collect();
+        let page_counts: Vec<Option<i32>> = books_update.iter().map(|b| b.page_count).collect();
+        
+        sqlx::query(
+            r#"
+            UPDATE books SET 
+                title = data.title,
+                kind = data.kind,
+                series = data.series,
+                volume = data.volume,
+                page_count = data.page_count,
+                updated_at = NOW()
+            FROM (
+                SELECT * FROM UNNEST($1::uuid[], $2::text[], $3::text[], $4::text[], $5::int[], $6::int[])
+                AS t(book_id, title, kind, series, volume, page_count)
+            ) AS data
+            WHERE books.id = data.book_id
+            "#
+        )
+        .bind(&book_ids)
+        .bind(&titles)
+        .bind(&kinds)
+        .bind(&series)
+        .bind(&volumes)
+        .bind(&page_counts)
+        .execute(&mut *tx)
+        .await?;
+        
+        books_update.clear();
+    }
+    
+    // Batch update files using UNNEST
+    if !files_update.is_empty() {
+        let file_ids: Vec<Uuid> = files_update.iter().map(|f| f.file_id).collect();
+        let formats: Vec<String> = files_update.iter().map(|f| f.format.clone()).collect();
+        let sizes: Vec<i64> = files_update.iter().map(|f| f.size_bytes).collect();
+        let mtimes: Vec<DateTime<Utc>> = files_update.iter().map(|f| f.mtime).collect();
+        let fingerprints: Vec<String> = files_update.iter().map(|f| f.fingerprint.clone()).collect();
+        
+        sqlx::query(
+            r#"
+            UPDATE book_files SET 
+                format = data.format,
+                size_bytes = data.size,
+                mtime = data.mtime,
+                fingerprint = data.fp,
+                parse_status = 'ok',
+                parse_error_opt = NULL,
+                updated_at = NOW()
+            FROM (
+                SELECT * FROM UNNEST($1::uuid[], $2::text[], $3::bigint[], $4::timestamptz[], $5::text[])
+                AS t(file_id, format, size, mtime, fp)
+            ) AS data
+            WHERE book_files.id = data.file_id
+            "#
+        )
+        .bind(&file_ids)
+        .bind(&formats)
+        .bind(&sizes)
+        .bind(&mtimes)
+        .bind(&fingerprints)
+        .execute(&mut *tx)
+        .await?;
+        
+        files_update.clear();
+    }
+    
+    // Batch insert books using UNNEST
+    if !books_insert.is_empty() {
+        let book_ids: Vec<Uuid> = books_insert.iter().map(|b| b.book_id).collect();
+        let library_ids: Vec<Uuid> = books_insert.iter().map(|b| b.library_id).collect();
+        let kinds: Vec<String> = books_insert.iter().map(|b| b.kind.clone()).collect();
+        let titles: Vec<String> = books_insert.iter().map(|b| b.title.clone()).collect();
+        let series: Vec<Option<String>> = books_insert.iter().map(|b| b.series.clone()).collect();
+        let volumes: Vec<Option<i32>> = books_insert.iter().map(|b| b.volume).collect();
+        let page_counts: Vec<Option<i32>> = books_insert.iter().map(|b| b.page_count).collect();
+        let thumbnail_paths: Vec<Option<String>> = books_insert.iter().map(|b| b.thumbnail_path.clone()).collect();
+        
+        sqlx::query(
+            r#"
+            INSERT INTO books (id, library_id, kind, title, series, volume, page_count, thumbnail_path)
+            SELECT * FROM UNNEST($1::uuid[], $2::uuid[], $3::text[], $4::text[], $5::text[], $6::int[], $7::int[], $8::text[])
+            AS t(id, library_id, kind, title, series, volume, page_count, thumbnail_path)
+            "#
+        )
+        .bind(&book_ids)
+        .bind(&library_ids)
+        .bind(&kinds)
+        .bind(&titles)
+        .bind(&series)
+        .bind(&volumes)
+        .bind(&page_counts)
+        .bind(&thumbnail_paths)
+        .execute(&mut *tx)
+        .await?;
+        
+        books_insert.clear();
+    }
+    
+    // Batch insert files using UNNEST
+    if !files_insert.is_empty() {
+        let file_ids: Vec<Uuid> = files_insert.iter().map(|f| f.file_id).collect();
+        let book_ids: Vec<Uuid> = files_insert.iter().map(|f| f.book_id).collect();
+        let formats: Vec<String> = files_insert.iter().map(|f| f.format.clone()).collect();
+        let abs_paths: Vec<String> = files_insert.iter().map(|f| f.abs_path.clone()).collect();
+        let sizes: Vec<i64> = files_insert.iter().map(|f| f.size_bytes).collect();
+        let mtimes: Vec<DateTime<Utc>> = files_insert.iter().map(|f| f.mtime).collect();
+        let fingerprints: Vec<String> = files_insert.iter().map(|f| f.fingerprint.clone()).collect();
+        let statuses: Vec<String> = files_insert.iter().map(|f| f.parse_status.clone()).collect();
+        let errors: Vec<Option<String>> = files_insert.iter().map(|f| f.parse_error.clone()).collect();
+        
+        sqlx::query(
+            r#"
+            INSERT INTO book_files (id, book_id, format, abs_path, size_bytes, mtime, fingerprint, parse_status, parse_error_opt)
+            SELECT * FROM UNNEST($1::uuid[], $2::uuid[], $3::text[], $4::text[], $5::bigint[], $6::timestamptz[], $7::text[], $8::text[], $9::text[])
+            AS t(id, book_id, format, abs_path, size_bytes, mtime, fingerprint, parse_status, parse_error_opt)
+            "#
+        )
+        .bind(&file_ids)
+        .bind(&book_ids)
+        .bind(&formats)
+        .bind(&abs_paths)
+        .bind(&sizes)
+        .bind(&mtimes)
+        .bind(&fingerprints)
+        .bind(&statuses)
+        .bind(&errors)
+        .execute(&mut *tx)
+        .await?;
+        
+        files_insert.clear();
+    }
+    
+    // Batch insert errors using UNNEST
+    if !errors_insert.is_empty() {
+        let job_ids: Vec<Uuid> = errors_insert.iter().map(|e| e.job_id).collect();
+        let file_paths: Vec<String> = errors_insert.iter().map(|e| e.file_path.clone()).collect();
+        let messages: Vec<String> = errors_insert.iter().map(|e| e.error_message.clone()).collect();
+        
+        sqlx::query(
+            r#"
+            INSERT INTO index_job_errors (job_id, file_path, error_message)
+            SELECT * FROM UNNEST($1::uuid[], $2::text[], $3::text[])
+            AS t(job_id, file_path, error_message)
+            "#
+        )
+        .bind(&job_ids)
+        .bind(&file_paths)
+        .bind(&messages)
+        .execute(&mut *tx)
+        .await?;
+        
+        errors_insert.clear();
+    }
+    
+    tx.commit().await?;
+    tracing::info!("[BATCH] Flushed all batches in {:?}", start.elapsed());
+    
+    Ok(())
+}

apps/indexer/src/converter.rs

@@ -0,0 +1,108 @@
+use anyhow::Result;
+use sqlx::Row;
+use tracing::{info, warn};
+use uuid::Uuid;
+
+use crate::{utils, AppState};
+
+/// Execute a `cbr_to_cbz` job for the given `book_id`.
+///
+/// Flow:
+/// 1. Read book file info from DB
+/// 2. Resolve physical path
+/// 3. Convert CBR → CBZ via `parsers::convert_cbr_to_cbz`
+/// 4. Update `book_files` and `books` in DB
+/// 5. Delete the original CBR (failure here does not fail the job)
+/// 6. Mark job as success
+pub async fn convert_book(state: &AppState, job_id: Uuid, book_id: Uuid) -> Result<()> {
+    info!("[CONVERTER] Starting CBR→CBZ conversion for book {} (job {})", book_id, job_id);
+
+    // Fetch current file info
+    let row = sqlx::query(
+        r#"
+        SELECT bf.id as file_id, bf.abs_path, bf.format
+        FROM book_files bf
+        WHERE bf.book_id = $1
+        ORDER BY bf.updated_at DESC
+        LIMIT 1
+        "#,
+    )
+    .bind(book_id)
+    .fetch_optional(&state.pool)
+    .await?;
+
+    let row = row.ok_or_else(|| anyhow::anyhow!("no book file found for book {}", book_id))?;
+
+    let file_id: Uuid = row.get("file_id");
+    let abs_path: String = row.get("abs_path");
+    let format: String = row.get("format");
+
+    if format != "cbr" {
+        return Err(anyhow::anyhow!(
+            "book {} is not CBR (format={}), skipping conversion",
+            book_id,
+            format
+        ));
+    }
+
+    let physical_path = utils::remap_libraries_path(&abs_path);
+    let cbr_path = std::path::Path::new(&physical_path);
+
+    info!("[CONVERTER] Converting {} → CBZ", cbr_path.display());
+
+    // Update job status to running (already set by claim_next_job, this updates current_file)
+    sqlx::query(
+        "UPDATE index_jobs SET current_file = $2 WHERE id = $1",
+    )
+    .bind(job_id)
+    .bind(&abs_path)
+    .execute(&state.pool)
+    .await?;
+
+    // Do the conversion
+    let cbz_path = parsers::convert_cbr_to_cbz(cbr_path)?;
+
+    info!("[CONVERTER] CBZ created at {}", cbz_path.display());
+
+    // Remap physical path back to /libraries/ canonical form
+    let new_abs_path = utils::unmap_libraries_path(&cbz_path.to_string_lossy());
+
+    // Update book_files: abs_path + format
+    sqlx::query(
+        "UPDATE book_files SET abs_path = $2, format = 'cbz', updated_at = NOW() WHERE id = $1",
+    )
+    .bind(file_id)
+    .bind(&new_abs_path)
+    .execute(&state.pool)
+    .await?;
+
+    // Update books: kind stays 'comic', updated_at refreshed
+    sqlx::query("UPDATE books SET updated_at = NOW() WHERE id = $1")
+        .bind(book_id)
+        .execute(&state.pool)
+        .await?;
+
+    info!("[CONVERTER] DB updated for book {}", book_id);
+
+    // Delete the original CBR file (best-effort)
+    if let Err(e) = std::fs::remove_file(cbr_path) {
+        warn!(
+            "[CONVERTER] Could not delete original CBR {}: {} (non-fatal)",
+            cbr_path.display(),
+            e
+        );
+    } else {
+        info!("[CONVERTER] Deleted original CBR {}", cbr_path.display());
+    }
+
+    // Mark job success
+    sqlx::query(
+        "UPDATE index_jobs SET status = 'success', finished_at = NOW(), progress_percent = 100, current_file = NULL WHERE id = $1",
+    )
+    .bind(job_id)
+    .execute(&state.pool)
+    .await?;
+
+    info!("[CONVERTER] Job {} completed successfully", job_id);
+    Ok(())
+}

apps/indexer/src/job.rs

@@ -0,0 +1,341 @@
+use anyhow::Result;
+use rayon::prelude::*;
+use sqlx::{PgPool, Row};
+use tracing::{error, info};
+use uuid::Uuid;
+
+use crate::{analyzer, converter, meili, scanner, AppState};
+
+pub async fn cleanup_stale_jobs(pool: &PgPool) -> Result<()> {
+    let result = sqlx::query(
+        r#"
+        UPDATE index_jobs
+        SET status = 'failed',
+            finished_at = NOW(),
+            error_opt = 'Job interrupted by indexer restart'
+        WHERE status = 'running'
+          AND started_at < NOW() - INTERVAL '5 minutes'
+        RETURNING id
+        "#,
+    )
+    .fetch_all(pool)
+    .await?;
+
+    if !result.is_empty() {
+        let count = result.len();
+        let ids: Vec<String> = result
+            .iter()
+            .map(|row| row.get::<Uuid, _>("id").to_string())
+            .collect();
+        info!(
+            "[CLEANUP] Marked {} stale job(s) as failed: {}",
+            count,
+            ids.join(", ")
+        );
+    }
+
+    Ok(())
+}
+
+pub async fn claim_next_job(pool: &PgPool) -> Result<Option<(Uuid, Option<Uuid>)>> {
+    let mut tx = pool.begin().await?;
+
+    let row = sqlx::query(
+        r#"
+        SELECT j.id, j.type, j.library_id
+        FROM index_jobs j
+        WHERE j.status = 'pending'
+          AND (
+            (j.type IN ('rebuild', 'full_rebuild') AND NOT EXISTS (
+                SELECT 1 FROM index_jobs
+                WHERE status = 'running'
+                  AND type IN ('rebuild', 'full_rebuild')
+            ))
+            OR
+            j.type NOT IN ('rebuild', 'full_rebuild')
+          )
+        ORDER BY
+            CASE j.type
+                WHEN 'full_rebuild' THEN 1
+                WHEN 'rebuild' THEN 2
+                ELSE 3
+            END,
+            j.created_at ASC
+        FOR UPDATE SKIP LOCKED
+        LIMIT 1
+        "#,
+    )
+    .fetch_optional(&mut *tx)
+    .await?;
+
+    let Some(row) = row else {
+        tx.commit().await?;
+        return Ok(None);
+    };
+
+    let id: Uuid = row.get("id");
+    let job_type: String = row.get("type");
+    let library_id: Option<Uuid> = row.get("library_id");
+
+    if job_type == "rebuild" || job_type == "full_rebuild" {
+        let has_running_rebuild: bool = sqlx::query_scalar(
+            r#"
+            SELECT EXISTS(
+                SELECT 1 FROM index_jobs
+                WHERE status = 'running'
+                  AND type IN ('rebuild', 'full_rebuild')
+                  AND id != $1
+            )
+            "#,
+        )
+        .bind(id)
+        .fetch_one(&mut *tx)
+        .await?;
+
+        if has_running_rebuild {
+            tx.rollback().await?;
+            return Ok(None);
+        }
+    }
+
+    sqlx::query(
+        "UPDATE index_jobs SET status = 'running', started_at = NOW(), error_opt = NULL WHERE id = $1",
+    )
+    .bind(id)
+    .execute(&mut *tx)
+    .await?;
+
+    tx.commit().await?;
+    Ok(Some((id, library_id)))
+}
+
+pub async fn fail_job(pool: &PgPool, job_id: Uuid, error_message: &str) -> Result<()> {
+    sqlx::query(
+        "UPDATE index_jobs SET status = 'failed', finished_at = NOW(), error_opt = $2 WHERE id = $1",
+    )
+    .bind(job_id)
+    .bind(error_message)
+    .execute(pool)
+    .await?;
+    Ok(())
+}
+
+pub async fn is_job_cancelled(pool: &PgPool, job_id: Uuid) -> Result<bool> {
+    let status: Option<String> =
+        sqlx::query_scalar("SELECT status FROM index_jobs WHERE id = $1")
+            .bind(job_id)
+            .fetch_optional(pool)
+            .await?;
+
+    Ok(status.as_deref() == Some("cancelled"))
+}
+
+pub async fn process_job(
+    state: &AppState,
+    job_id: Uuid,
+    target_library_id: Option<Uuid>,
+) -> Result<()> {
+    info!("[JOB] Processing {} library={:?}", job_id, target_library_id);
+
+    let (job_type, book_id): (String, Option<Uuid>) = {
+        let row = sqlx::query("SELECT type, book_id FROM index_jobs WHERE id = $1")
+            .bind(job_id)
+            .fetch_one(&state.pool)
+            .await?;
+        (row.get("type"), row.get("book_id"))
+    };
+
+    // CBR to CBZ conversion
+    if job_type == "cbr_to_cbz" {
+        let book_id = book_id.ok_or_else(|| {
+            anyhow::anyhow!("cbr_to_cbz job {} has no book_id", job_id)
+        })?;
+        converter::convert_book(state, job_id, book_id).await?;
+        return Ok(());
+    }
+
+    // Thumbnail rebuild: generate thumbnails for books missing them
+    if job_type == "thumbnail_rebuild" {
+        sqlx::query(
+            "UPDATE index_jobs SET status = 'generating_thumbnails', started_at = NOW(), phase2_started_at = NOW() WHERE id = $1",
+        )
+        .bind(job_id)
+        .execute(&state.pool)
+        .await?;
+
+        analyzer::analyze_library_books(state, job_id, target_library_id, true).await?;
+
+        sqlx::query(
+            "UPDATE index_jobs SET status = 'success', finished_at = NOW(), progress_percent = 100, current_file = NULL WHERE id = $1",
+        )
+        .bind(job_id)
+        .execute(&state.pool)
+        .await?;
+
+        return Ok(());
+    }
+
+    // Thumbnail regenerate: clear all thumbnails then re-generate
+    if job_type == "thumbnail_regenerate" {
+        sqlx::query(
+            "UPDATE index_jobs SET status = 'generating_thumbnails', started_at = NOW(), phase2_started_at = NOW() WHERE id = $1",
+        )
+        .bind(job_id)
+        .execute(&state.pool)
+        .await?;
+
+        analyzer::regenerate_thumbnails(state, job_id, target_library_id).await?;
+
+        sqlx::query(
+            "UPDATE index_jobs SET status = 'success', finished_at = NOW(), progress_percent = 100, current_file = NULL WHERE id = $1",
+        )
+        .bind(job_id)
+        .execute(&state.pool)
+        .await?;
+
+        return Ok(());
+    }
+
+    let is_full_rebuild = job_type == "full_rebuild";
+    info!(
+        "[JOB] {} type={} full_rebuild={}",
+        job_id, job_type, is_full_rebuild
+    );
+
+    // Full rebuild: delete existing data first
+    if is_full_rebuild {
+        info!("[JOB] Full rebuild: deleting existing data");
+
+        if let Some(library_id) = target_library_id {
+            sqlx::query(
+                "DELETE FROM book_files WHERE book_id IN (SELECT id FROM books WHERE library_id = $1)",
+            )
+            .bind(library_id)
+            .execute(&state.pool)
+            .await?;
+            sqlx::query("DELETE FROM books WHERE library_id = $1")
+                .bind(library_id)
+                .execute(&state.pool)
+                .await?;
+            info!("[JOB] Deleted existing data for library {}", library_id);
+        } else {
+            sqlx::query("DELETE FROM book_files")
+                .execute(&state.pool)
+                .await?;
+            sqlx::query("DELETE FROM books").execute(&state.pool).await?;
+            info!("[JOB] Deleted all existing data");
+        }
+    }
+
+    let libraries = if let Some(library_id) = target_library_id {
+        sqlx::query("SELECT id, root_path FROM libraries WHERE id = $1 AND enabled = TRUE")
+            .bind(library_id)
+            .fetch_all(&state.pool)
+            .await?
+    } else {
+        sqlx::query("SELECT id, root_path FROM libraries WHERE enabled = TRUE")
+            .fetch_all(&state.pool)
+            .await?
+    };
+
+    // Count total files for progress estimation
+    let library_paths: Vec<String> = libraries
+        .iter()
+        .map(|library| {
+            crate::utils::remap_libraries_path(&library.get::<String, _>("root_path"))
+        })
+        .collect();
+
+    let total_files: usize = library_paths
+        .par_iter()
+        .map(|root_path| {
+            walkdir::WalkDir::new(root_path)
+                .into_iter()
+                .filter_map(Result::ok)
+                .filter(|entry| {
+                    entry.file_type().is_file()
+                        && parsers::detect_format(entry.path()).is_some()
+                })
+                .count()
+        })
+        .sum();
+
+    info!(
+        "[JOB] Found {} libraries, {} total files to index",
+        libraries.len(),
+        total_files
+    );
+
+    sqlx::query("UPDATE index_jobs SET total_files = $2 WHERE id = $1")
+        .bind(job_id)
+        .bind(total_files as i32)
+        .execute(&state.pool)
+        .await?;
+
+    let mut stats = scanner::JobStats {
+        scanned_files: 0,
+        indexed_files: 0,
+        removed_files: 0,
+        errors: 0,
+    };
+
+    let mut total_processed_count = 0i32;
+
+    // Phase 1: Discovery
+    for library in &libraries {
+        let library_id: Uuid = library.get("id");
+        let root_path: String = library.get("root_path");
+        let root_path = crate::utils::remap_libraries_path(&root_path);
+        match scanner::scan_library_discovery(
+            state,
+            job_id,
+            library_id,
+            std::path::Path::new(&root_path),
+            &mut stats,
+            &mut total_processed_count,
+            total_files,
+            is_full_rebuild,
+        )
+        .await
+        {
+            Ok(()) => {}
+            Err(err) => {
+                let err_str = err.to_string();
+                if err_str.contains("cancelled") || err_str.contains("Cancelled") {
+                    return Err(err);
+                }
+                stats.errors += 1;
+                error!(library_id = %library_id, error = %err, "library scan failed");
+            }
+        }
+    }
+
+    // Sync search index after discovery (books are visible immediately)
+    meili::sync_meili(&state.pool, &state.meili_url, &state.meili_master_key).await?;
+
+    // For full rebuild: clean up orphaned thumbnail files (old UUIDs)
+    if is_full_rebuild {
+        analyzer::cleanup_orphaned_thumbnails(state).await?;
+    }
+
+    // Phase 2: Analysis (extract page_count + thumbnails for new/updated books)
+    sqlx::query(
+        "UPDATE index_jobs SET status = 'generating_thumbnails', phase2_started_at = NOW(), stats_json = $2, current_file = NULL, processed_files = $3 WHERE id = $1",
+    )
+    .bind(job_id)
+    .bind(serde_json::to_value(&stats)?)
+    .bind(total_processed_count)
+    .execute(&state.pool)
+    .await?;
+
+    analyzer::analyze_library_books(state, job_id, target_library_id, false).await?;
+
+    sqlx::query(
+        "UPDATE index_jobs SET status = 'success', finished_at = NOW(), progress_percent = 100, current_file = NULL WHERE id = $1",
+    )
+    .bind(job_id)
+    .execute(&state.pool)
+    .await?;
+
+    Ok(())
+}

apps/indexer/src/lib.rs

@@ -0,0 +1,20 @@
+pub mod analyzer;
+pub mod api;
+pub mod batch;
+pub mod converter;
+pub mod job;
+pub mod meili;
+pub mod scheduler;
+pub mod scanner;
+pub mod utils;
+pub mod watcher;
+pub mod worker;
+
+use sqlx::PgPool;
+
+#[derive(Clone)]
+pub struct AppState {
+    pub pool: PgPool,
+    pub meili_url: String,
+    pub meili_master_key: String,
+}

apps/indexer/src/meili.rs

@@ -0,0 +1,180 @@
+use anyhow::{Context, Result};
+use chrono::{DateTime, Utc};
+use reqwest::Client;
+use serde::Serialize;
+use sqlx::{PgPool, Row};
+use tracing::info;
+use uuid::Uuid;
+
+#[derive(Serialize)]
+struct SearchDoc {
+    id: String,
+    library_id: String,
+    kind: String,
+    title: String,
+    author: Option<String>,
+    series: Option<String>,
+    volume: Option<i32>,
+    language: Option<String>,
+}
+
+pub async fn sync_meili(pool: &PgPool, meili_url: &str, meili_master_key: &str) -> Result<()> {
+    let client = Client::new();
+    let base = meili_url.trim_end_matches('/');
+
+    // Ensure index exists and has proper settings
+    let _ = client
+        .post(format!("{base}/indexes"))
+        .header("Authorization", format!("Bearer {meili_master_key}"))
+        .json(&serde_json::json!({"uid": "books", "primaryKey": "id"}))
+        .send()
+        .await;
+
+    let _ = client
+        .patch(format!("{base}/indexes/books/settings/filterable-attributes"))
+        .header("Authorization", format!("Bearer {meili_master_key}"))
+        .json(&serde_json::json!(["library_id", "kind"]))
+        .send()
+        .await;
+
+    // Get last sync timestamp
+    let last_sync: Option<DateTime<Utc>> = sqlx::query_scalar(
+        "SELECT last_meili_sync FROM sync_metadata WHERE id = 1 AND last_meili_sync IS NOT NULL"
+    )
+    .fetch_optional(pool)
+    .await?;
+
+    // If no previous sync, do a full sync
+    let is_full_sync = last_sync.is_none();
+    
+    // Get books to sync: all if full sync, only modified since last sync otherwise
+    let rows = if is_full_sync {
+        info!("[MEILI] Performing full sync");
+        sqlx::query(
+            "SELECT id, library_id, kind, title, author, series, volume, language, updated_at FROM books",
+        )
+        .fetch_all(pool)
+        .await?
+    } else {
+        let since = last_sync.unwrap();
+        info!("[MEILI] Performing incremental sync since {}", since);
+        
+        // Also get deleted book IDs to remove from MeiliSearch
+        // For now, we'll do a diff approach: get all book IDs from DB and compare with Meili
+        sqlx::query(
+            "SELECT id, library_id, kind, title, author, series, volume, language, updated_at FROM books WHERE updated_at > $1",
+        )
+        .bind(since)
+        .fetch_all(pool)
+        .await?
+    };
+
+    if rows.is_empty() && !is_full_sync {
+        info!("[MEILI] No changes to sync");
+        // Still update the timestamp
+        sqlx::query(
+            "INSERT INTO sync_metadata (id, last_meili_sync) VALUES (1, NOW()) ON CONFLICT (id) DO UPDATE SET last_meili_sync = NOW()"
+        )
+        .execute(pool)
+        .await?;
+        return Ok(());
+    }
+
+    let docs: Vec<SearchDoc> = rows
+        .into_iter()
+        .map(|row| SearchDoc {
+            id: row.get::<Uuid, _>("id").to_string(),
+            library_id: row.get::<Uuid, _>("library_id").to_string(),
+            kind: row.get("kind"),
+            title: row.get("title"),
+            author: row.get("author"),
+            series: row.get("series"),
+            volume: row.get("volume"),
+            language: row.get("language"),
+        })
+        .collect();
+
+    let doc_count = docs.len();
+    
+    // Send documents to MeiliSearch in batches of 1000
+    const MEILI_BATCH_SIZE: usize = 1000;
+    for (i, chunk) in docs.chunks(MEILI_BATCH_SIZE).enumerate() {
+        let batch_num = i + 1;
+        info!("[MEILI] Sending batch {}/{} ({} docs)", batch_num, doc_count.div_ceil(MEILI_BATCH_SIZE), chunk.len());
+        
+        let response = client
+            .post(format!("{base}/indexes/books/documents"))
+            .header("Authorization", format!("Bearer {meili_master_key}"))
+            .json(&chunk)
+            .send()
+            .await
+            .context("failed to send docs to meili")?;
+        
+        if !response.status().is_success() {
+            let status = response.status();
+            let body = response.text().await.unwrap_or_default();
+            return Err(anyhow::anyhow!("MeiliSearch error {}: {}", status, body));
+        }
+    }
+
+    // Handle deletions: get all book IDs from DB and remove from MeiliSearch any that don't exist
+    // This is expensive, so we only do it periodically (every 10 syncs) or on full syncs
+    if is_full_sync || rand::random::<u8>() < 26 { // ~10% chance
+        info!("[MEILI] Checking for documents to delete");
+        
+        // Get all book IDs from database
+        let db_ids: Vec<String> = sqlx::query_scalar("SELECT id::text FROM books")
+            .fetch_all(pool)
+            .await?;
+        
+        // Get all document IDs from MeiliSearch (this requires fetching all documents)
+        // For efficiency, we'll just delete by query for documents that might be stale
+        // A better approach would be to track deletions in a separate table
+        
+        // For now, we'll do a simple approach: fetch all Meili docs and compare
+        // Note: This could be slow for large collections
+        let meili_response = client
+            .post(format!("{base}/indexes/books/documents/fetch"))
+            .header("Authorization", format!("Bearer {meili_master_key}"))
+            .json(&serde_json::json!({
+                "fields": ["id"],
+                "limit": 100000
+            }))
+            .send()
+            .await;
+        
+        if let Ok(response) = meili_response {
+            if response.status().is_success() {
+                if let Ok(meili_docs) = response.json::<Vec<serde_json::Value>>().await {
+                    let meili_ids: std::collections::HashSet<String> = meili_docs
+                        .into_iter()
+                        .filter_map(|doc| doc.get("id").and_then(|id| id.as_str()).map(|s| s.to_string()))
+                        .collect();
+                    
+                    let db_ids_set: std::collections::HashSet<String> = db_ids.into_iter().collect();
+                    let to_delete: Vec<String> = meili_ids.difference(&db_ids_set).cloned().collect();
+                    
+                    if !to_delete.is_empty() {
+                        info!("[MEILI] Deleting {} stale documents", to_delete.len());
+                        let _ = client
+                            .post(format!("{base}/indexes/books/documents/delete-batch"))
+                            .header("Authorization", format!("Bearer {meili_master_key}"))
+                            .json(&to_delete)
+                            .send()
+                            .await;
+                    }
+                }
+            }
+        }
+    }
+
+    // Update last sync timestamp
+    sqlx::query(
+        "INSERT INTO sync_metadata (id, last_meili_sync) VALUES (1, NOW()) ON CONFLICT (id) DO UPDATE SET last_meili_sync = NOW()"
+    )
+    .execute(pool)
+    .await?;
+
+    info!("[MEILI] Sync completed: {} documents indexed", doc_count);
+    Ok(())
+}

apps/indexer/src/scanner.rs

@@ -0,0 +1,443 @@
+use anyhow::{Context, Result};
+use chrono::{DateTime, Utc};
+use parsers::{detect_format, parse_metadata_fast};
+use serde::Serialize;
+use sqlx::Row;
+use std::{collections::HashMap, path::Path, time::Duration};
+use tracing::{error, info, trace, warn};
+use uuid::Uuid;
+use walkdir::WalkDir;
+
+use crate::{
+    batch::{flush_all_batches, BookInsert, BookUpdate, ErrorInsert, FileInsert, FileUpdate},
+    job::is_job_cancelled,
+    utils,
+    AppState,
+};
+
+#[derive(Serialize)]
+pub struct JobStats {
+    pub scanned_files: usize,
+    pub indexed_files: usize,
+    pub removed_files: usize,
+    pub errors: usize,
+}
+
+const BATCH_SIZE: usize = 100;
+
+/// Phase 1 — Discovery: walk filesystem, extract metadata from filenames only (no archive I/O).
+/// New books are inserted with page_count = NULL so the analyzer phase can fill them in.
+/// Updated books (fingerprint changed) get page_count/thumbnail reset.
+#[allow(clippy::too_many_arguments)]
+pub async fn scan_library_discovery(
+    state: &AppState,
+    job_id: Uuid,
+    library_id: Uuid,
+    root: &Path,
+    stats: &mut JobStats,
+    total_processed_count: &mut i32,
+    total_files: usize,
+    is_full_rebuild: bool,
+) -> Result<()> {
+    info!(
+        "[SCAN] Starting discovery scan of library {} at path: {} (full_rebuild={})",
+        library_id,
+        root.display(),
+        is_full_rebuild
+    );
+
+    // Load existing files from DB
+    let existing_rows = sqlx::query(
+        r#"
+        SELECT bf.id AS file_id, bf.book_id, bf.abs_path, bf.fingerprint
+        FROM book_files bf
+        JOIN books b ON b.id = bf.book_id
+        WHERE b.library_id = $1
+        "#,
+    )
+    .bind(library_id)
+    .fetch_all(&state.pool)
+    .await?;
+
+    let mut existing: HashMap<String, (Uuid, Uuid, String)> = HashMap::new();
+    if !is_full_rebuild {
+        for row in existing_rows {
+            let abs_path: String = row.get("abs_path");
+            let remapped_path = utils::remap_libraries_path(&abs_path);
+            existing.insert(
+                remapped_path,
+                (row.get("file_id"), row.get("book_id"), row.get("fingerprint")),
+            );
+        }
+        info!(
+            "[SCAN] Found {} existing files in database for library {}",
+            existing.len(),
+            library_id
+        );
+    } else {
+        info!("[SCAN] Full rebuild: skipping existing files lookup");
+        // Delete stale directory mtime records for full rebuild
+        let _ = sqlx::query("DELETE FROM directory_mtimes WHERE library_id = $1")
+            .bind(library_id)
+            .execute(&state.pool)
+            .await;
+    }
+
+    // Load stored directory mtimes for incremental skip
+    let dir_mtimes: HashMap<String, DateTime<Utc>> = if !is_full_rebuild {
+        let rows = sqlx::query(
+            "SELECT dir_path, mtime FROM directory_mtimes WHERE library_id = $1",
+        )
+        .bind(library_id)
+        .fetch_all(&state.pool)
+        .await
+        .unwrap_or_default();
+
+        rows.into_iter()
+            .map(|row| {
+                let db_path: String = row.get("dir_path");
+                let local_path = utils::remap_libraries_path(&db_path);
+                let mtime: DateTime<Utc> = row.get("mtime");
+                (local_path, mtime)
+            })
+            .collect()
+    } else {
+        HashMap::new()
+    };
+
+    let mut seen: HashMap<String, bool> = HashMap::new();
+    let mut library_processed_count = 0i32;
+    let mut last_progress_update = std::time::Instant::now();
+
+    // Batching buffers
+    let mut books_to_update: Vec<BookUpdate> = Vec::with_capacity(BATCH_SIZE);
+    let mut files_to_update: Vec<FileUpdate> = Vec::with_capacity(BATCH_SIZE);
+    let mut books_to_insert: Vec<BookInsert> = Vec::with_capacity(BATCH_SIZE);
+    let mut files_to_insert: Vec<FileInsert> = Vec::with_capacity(BATCH_SIZE);
+    let mut errors_to_insert: Vec<ErrorInsert> = Vec::with_capacity(BATCH_SIZE);
+
+    // Track discovered directory mtimes for upsert after scan
+    let mut new_dir_mtimes: Vec<(String, DateTime<Utc>)> = Vec::new();
+
+    // Prefixes (with trailing "/") of directories whose mtime hasn't changed.
+    // Files under these prefixes are added to `seen` but not reprocessed.
+    let mut skipped_dir_prefixes: Vec<String> = Vec::new();
+
+    for entry in WalkDir::new(root).into_iter().filter_map(Result::ok) {
+        let path = entry.path().to_path_buf();
+        let local_path = path.to_string_lossy().to_string();
+
+        if entry.file_type().is_dir() {
+            if entry.depth() == 0 {
+                continue; // skip root itself
+            }
+
+            // Check if parent dir is already skipped (propagate skip to subdirs)
+            let already_under_skipped = skipped_dir_prefixes
+                .iter()
+                .any(|p| local_path.starts_with(p.as_str()));
+
+            if let Ok(meta) = entry.metadata() {
+                if let Ok(sys_mtime) = meta.modified() {
+                    let mtime_utc: DateTime<Utc> = DateTime::from(sys_mtime);
+
+                    // Only record mtimes for non-skipped dirs (to avoid polluting DB)
+                    if !already_under_skipped {
+                        new_dir_mtimes.push((local_path.clone(), mtime_utc));
+                    }
+
+                    // Skip if mtime unchanged (incremental only, not already skipped subtree)
+                    if !is_full_rebuild && !already_under_skipped {
+                        if let Some(&stored_mtime) = dir_mtimes.get(&local_path) {
+                            if mtime_utc <= stored_mtime {
+                                trace!("[SCAN] Skipping unchanged dir: {}", local_path);
+                                // Add trailing slash so starts_with check is exact per-segment
+                                skipped_dir_prefixes.push(format!("{}/", local_path));
+                            }
+                        }
+                    }
+                }
+            }
+            continue;
+        }
+
+        if !entry.file_type().is_file() {
+            continue;
+        }
+
+        // Check if this file is under a skipped dir
+        let under_skipped = skipped_dir_prefixes
+            .iter()
+            .any(|p| local_path.starts_with(p.as_str()));
+
+        if under_skipped {
+            // Dir unchanged — just mark file as seen so it's not deleted
+            let abs_path_local = local_path.clone();
+            let abs_path = utils::unmap_libraries_path(&abs_path_local);
+            let lookup_path = utils::remap_libraries_path(&abs_path);
+            seen.insert(lookup_path, true);
+            continue;
+        }
+
+        let Some(format) = detect_format(&path) else {
+            trace!("[SCAN] Skipping non-book file: {}", path.display());
+            continue;
+        };
+
+        info!(
+            "[SCAN] Found book file: {} (format: {:?})",
+            path.display(),
+            format
+        );
+        stats.scanned_files += 1;
+
+        let abs_path_local = path.to_string_lossy().to_string();
+        let abs_path = utils::unmap_libraries_path(&abs_path_local);
+        let file_name = path
+            .file_name()
+            .map(|s| s.to_string_lossy().to_string())
+            .unwrap_or_else(|| abs_path.clone());
+
+        let metadata = std::fs::metadata(&path)
+            .with_context(|| format!("cannot stat {}", path.display()))?;
+        let mtime: DateTime<Utc> = metadata
+            .modified()
+            .map(DateTime::<Utc>::from)
+            .unwrap_or_else(|_| Utc::now());
+        let fingerprint = utils::compute_fingerprint(&path, metadata.len(), &mtime)?;
+        let lookup_path = utils::remap_libraries_path(&abs_path);
+
+        library_processed_count += 1;
+        *total_processed_count += 1;
+
+        // Progress update
+        let should_update_progress = last_progress_update.elapsed() > Duration::from_secs(1)
+            || library_processed_count % 10 == 0;
+        if should_update_progress {
+            let progress_percent = if total_files > 0 {
+                ((*total_processed_count as f64 / total_files as f64) * 100.0) as i32
+            } else {
+                0
+            };
+
+            sqlx::query(
+                "UPDATE index_jobs SET current_file = $2, processed_files = $3, progress_percent = $4 WHERE id = $1",
+            )
+            .bind(job_id)
+            .bind(&file_name)
+            .bind(*total_processed_count)
+            .bind(progress_percent)
+            .execute(&state.pool)
+            .await
+            .map_err(|e| {
+                error!("[BDD] Failed to update progress for job {}: {}", job_id, e);
+                e
+            })?;
+
+            last_progress_update = std::time::Instant::now();
+
+            if is_job_cancelled(&state.pool, job_id).await? {
+                info!("[JOB] Job {} cancelled by user, stopping...", job_id);
+                flush_all_batches(
+                    &state.pool,
+                    &mut books_to_update,
+                    &mut files_to_update,
+                    &mut books_to_insert,
+                    &mut files_to_insert,
+                    &mut errors_to_insert,
+                )
+                .await?;
+                return Err(anyhow::anyhow!("Job cancelled by user"));
+            }
+        }
+
+        seen.insert(lookup_path.clone(), true);
+
+        // Fast metadata extraction — no archive I/O
+        let parsed = parse_metadata_fast(&path, format, root);
+
+        if let Some((file_id, book_id, old_fingerprint)) =
+            existing.get(&lookup_path).cloned()
+        {
+            if !is_full_rebuild && old_fingerprint == fingerprint {
+                trace!("[PROCESS] Skipping unchanged file: {}", file_name);
+                continue;
+            }
+
+            info!(
+                "[PROCESS] Updating existing file: {} (fingerprint_changed={})",
+                file_name,
+                old_fingerprint != fingerprint
+            );
+
+            books_to_update.push(BookUpdate {
+                book_id,
+                title: parsed.title,
+                kind: utils::kind_from_format(format).to_string(),
+                series: parsed.series,
+                volume: parsed.volume,
+                // Reset page_count so analyzer re-processes this book
+                page_count: None,
+            });
+
+            files_to_update.push(FileUpdate {
+                file_id,
+                format: format.as_str().to_string(),
+                size_bytes: metadata.len() as i64,
+                mtime,
+                fingerprint,
+            });
+
+            // Also clear thumbnail so it gets regenerated
+            if let Err(e) = sqlx::query(
+                "UPDATE books SET thumbnail_path = NULL WHERE id = $1",
+            )
+            .bind(book_id)
+            .execute(&state.pool)
+            .await
+            {
+                warn!(
+                    "[BDD] Failed to clear thumbnail for book {}: {}",
+                    book_id, e
+                );
+            }
+
+            stats.indexed_files += 1;
+
+            if books_to_update.len() >= BATCH_SIZE || files_to_update.len() >= BATCH_SIZE {
+                flush_all_batches(
+                    &state.pool,
+                    &mut books_to_update,
+                    &mut files_to_update,
+                    &mut books_to_insert,
+                    &mut files_to_insert,
+                    &mut errors_to_insert,
+                )
+                .await?;
+            }
+
+            continue;
+        }
+
+        // New file — insert with page_count = NULL (analyzer fills it in)
+        info!("[PROCESS] Inserting new file: {}", file_name);
+        let book_id = Uuid::new_v4();
+        let file_id = Uuid::new_v4();
+
+        books_to_insert.push(BookInsert {
+            book_id,
+            library_id,
+            kind: utils::kind_from_format(format).to_string(),
+            title: parsed.title,
+            series: parsed.series,
+            volume: parsed.volume,
+            page_count: None,
+            thumbnail_path: None,
+        });
+
+        files_to_insert.push(FileInsert {
+            file_id,
+            book_id,
+            format: format.as_str().to_string(),
+            abs_path: abs_path.clone(),
+            size_bytes: metadata.len() as i64,
+            mtime,
+            fingerprint,
+            parse_status: "ok".to_string(),
+            parse_error: None,
+        });
+
+        stats.indexed_files += 1;
+
+        if books_to_insert.len() >= BATCH_SIZE || files_to_insert.len() >= BATCH_SIZE {
+            flush_all_batches(
+                &state.pool,
+                &mut books_to_update,
+                &mut files_to_update,
+                &mut books_to_insert,
+                &mut files_to_insert,
+                &mut errors_to_insert,
+            )
+            .await?;
+        }
+    }
+
+    // Flush remaining batches
+    flush_all_batches(
+        &state.pool,
+        &mut books_to_update,
+        &mut files_to_update,
+        &mut books_to_insert,
+        &mut files_to_insert,
+        &mut errors_to_insert,
+    )
+    .await?;
+
+    if !skipped_dir_prefixes.is_empty() {
+        info!(
+            "[SCAN] Skipped {} unchanged directories",
+            skipped_dir_prefixes.len()
+        );
+    }
+
+    info!(
+        "[SCAN] Library {} discovery complete: {} files scanned, {} indexed, {} errors",
+        library_id, library_processed_count, stats.indexed_files, stats.errors
+    );
+
+    // Handle deletions
+    let mut removed_count = 0usize;
+    for (abs_path, (file_id, book_id, _)) in &existing {
+        if seen.contains_key(abs_path) {
+            continue;
+        }
+        sqlx::query("DELETE FROM book_files WHERE id = $1")
+            .bind(file_id)
+            .execute(&state.pool)
+            .await?;
+        sqlx::query(
+            "DELETE FROM books WHERE id = $1 AND NOT EXISTS (SELECT 1 FROM book_files WHERE book_id = $1)",
+        )
+        .bind(book_id)
+        .execute(&state.pool)
+        .await?;
+        stats.removed_files += 1;
+        removed_count += 1;
+    }
+
+    if removed_count > 0 {
+        info!(
+            "[SCAN] Removed {} stale files from database",
+            removed_count
+        );
+    }
+
+    // Upsert directory mtimes for next incremental scan
+    if !new_dir_mtimes.is_empty() {
+        let dir_paths_db: Vec<String> = new_dir_mtimes
+            .iter()
+            .map(|(local, _)| utils::unmap_libraries_path(local))
+            .collect();
+        let mtimes: Vec<DateTime<Utc>> = new_dir_mtimes.iter().map(|(_, m)| *m).collect();
+        let library_ids: Vec<Uuid> = vec![library_id; new_dir_mtimes.len()];
+
+        if let Err(e) = sqlx::query(
+            r#"
+            INSERT INTO directory_mtimes (library_id, dir_path, mtime)
+            SELECT * FROM UNNEST($1::uuid[], $2::text[], $3::timestamptz[])
+            AS t(library_id, dir_path, mtime)
+            ON CONFLICT (library_id, dir_path) DO UPDATE SET mtime = EXCLUDED.mtime
+            "#,
+        )
+        .bind(&library_ids)
+        .bind(&dir_paths_db)
+        .bind(&mtimes)
+        .execute(&state.pool)
+        .await
+        {
+            warn!("[SCAN] Failed to upsert directory mtimes: {}", e);
+        }
+    }
+
+    Ok(())
+}