feat(backoffice): add reading progress management, series page, and live search

- API: add POST /series/mark-read to batch mark all books in a series
- API: add GET /series cross-library endpoint with search, library and status filters
- API: add library_id to SeriesItem response
- Backoffice: mark book as read/unread button on book detail page
- Backoffice: mark series as read/unread button on series cards
- Backoffice: new /series top-level page with search and filters
- Backoffice: new /libraries/[id]/series/[name] series detail page
- Backoffice: opacity on fully read books and series cards
- Backoffice: live search with debounce on books and series pages
- Backoffice: reading status filter on books and series pages
- Fix $2 -> $1 parameter binding in mark-series-read SQL

Co-Authored-By: Claude Opus 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
@@ -34,6 +34,24 @@ MEILI_URL=http://meilisearch:7700
 # PostgreSQL Database
 DATABASE_URL=postgres://stripstream:stripstream@postgres:5432/stripstream
 
+# =============================================================================
+# Logging
+# =============================================================================
+# Log levels per domain. Default: indexer=info,scan=info,extraction=info,thumbnail=warn,watcher=info
+# Domains:
+#   scan        — filesystem scan (discovery phase)
+#   extraction  — page extraction from archives (extracting_pages phase)
+#   thumbnail   — thumbnail generation (resize/encode)
+#   watcher     — file watcher polling
+#   indexer     — general indexer logs
+# Levels: error, warn, info, debug, trace
+# Examples:
+#   RUST_LOG=indexer=info                                     # default, quiet thumbnails
+#   RUST_LOG=indexer=info,thumbnail=debug                     # enable thumbnail timing logs
+#   RUST_LOG=indexer=info,extraction=debug                    # per-book extraction details
+#   RUST_LOG=indexer=debug,scan=debug,extraction=debug,thumbnail=debug,watcher=debug  # tout voir
+# RUST_LOG=indexer=info,scan=info,extraction=info,thumbnail=warn,watcher=info
+
 # =============================================================================
 # Storage Configuration
 # =============================================================================
@@ -46,18 +64,18 @@ LIBRARIES_ROOT_PATH=/libraries
 # Path to libraries directory on host machine (for Docker volume mount)
 # Default: ../libraries (relative to infra/docker-compose.yml)
 # You can change this to an absolute path on your machine
-LIBRARIES_HOST_PATH=../libraries
+LIBRARIES_HOST_PATH=./libraries
 
 # Path to thumbnails directory on host machine (for Docker volume mount)
 # Default: ../data/thumbnails (relative to infra/docker-compose.yml)
-THUMBNAILS_HOST_PATH=../data/thumbnails
+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

@@ -51,7 +51,7 @@ checksum = "7f202df86484c868dbad7eaa557ef785d5c66295e41b460ef922eca0723b842c"
 
 [[package]]
 name = "api"
-version = "0.1.0"
+version = "0.2.0"
 dependencies = [
  "anyhow",
  "argon2",
@@ -61,7 +61,9 @@ dependencies = [
  "chrono",
  "futures",
  "image",
+ "jpeg-decoder",
  "lru",
+ "parsers",
  "rand 0.8.5",
  "reqwest",
  "serde",
@@ -78,18 +80,7 @@ dependencies = [
  "utoipa",
  "utoipa-swagger-ui",
  "uuid",
- "walkdir",
  "webp",
- "zip 2.4.2",
-]
-
-[[package]]
-name = "arbitrary"
-version = "1.4.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c3d036a3c4ab069c7b410a2ce876bd74808d2d0888a82667669f8e783a898bf1"
-dependencies = [
- "derive_arbitrary",
 ]
 
 [[package]]
@@ -225,12 +216,6 @@ version = "1.8.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "2af50177e190e07a26ab74f8b1efbfe2ef87da2116221318cb1c2e82baf7de06"
 
-[[package]]
-name = "bitflags"
-version = "1.3.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bef38d45163c2f1dde094a7dfd33ccf595c92905c8f8f4fdc18d06fb1037718a"
-
 [[package]]
 name = "bitflags"
 version = "2.11.0"
@@ -369,6 +354,26 @@ dependencies = [
  "crossbeam-utils",
 ]
 
+[[package]]
+name = "console_error_panic_hook"
+version = "0.1.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a06aeb73f470f66dcdbf7223caeebb85984942f22f1adb2a088cf9668146bbbc"
+dependencies = [
+ "cfg-if",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "console_log"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "be8aed40e4edbf4d3b4431ab260b63fdc40f5780a4766824329ea0f1eefe3c0f"
+dependencies = [
+ "log",
+ "web-sys",
+]
+
 [[package]]
 name = "const-oid"
 version = "0.9.6"
@@ -414,15 +419,6 @@ dependencies = [
  "cfg-if",
 ]
 
-[[package]]
-name = "crossbeam-channel"
-version = "0.5.15"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "82b8f8f868b36967f9606790d1903570de9ceaf870a7bf9fbbd3016d636a2cb2"
-dependencies = [
- "crossbeam-utils",
-]
-
 [[package]]
 name = "crossbeam-deque"
 version = "0.8.6"
@@ -487,17 +483,6 @@ dependencies = [
  "powerfmt",
 ]
 
-[[package]]
-name = "derive_arbitrary"
-version = "1.4.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1e567bd82dcff979e4b03460c307b3cdc9e96fde3d73bed1496d2bc75d9dd62a"
-dependencies = [
- "proc-macro2",
- "quote",
- "syn 2.0.117",
-]
-
 [[package]]
 name = "digest"
 version = "0.10.7"
@@ -527,6 +512,15 @@ version = "0.15.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1aaf95b3e5c8f23aa320147307562d361db0ae0d51242340f558153b4eb2439b"
 
+[[package]]
+name = "ecb"
+version = "0.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1a8bfa975b1aec2145850fcaa1c6fe269a16578c44705a532ae3edc92b8881c7"
+dependencies = [
+ "cipher",
+]
+
 [[package]]
 name = "either"
 version = "1.15.0"
@@ -592,17 +586,6 @@ dependencies = [
  "simd-adler32",
 ]
 
-[[package]]
-name = "filetime"
-version = "0.2.27"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f98844151eee8917efc50bd9e8318cb963ae8b297431495d3f758616ea5c57db"
-dependencies = [
- "cfg-if",
- "libc",
- "libredox",
-]
-
 [[package]]
 name = "find-msvc-tools"
 version = "0.1.9"
@@ -617,6 +600,7 @@ checksum = "843fba2746e448b37e26a819579957415c8cef339bf08564fe8b7ddbd959573c"
 dependencies = [
  "crc32fast",
  "miniz_oxide",
+ "zlib-rs",
 ]
 
 [[package]]
@@ -645,15 +629,6 @@ dependencies = [
  "percent-encoding",
 ]
 
-[[package]]
-name = "fsevent-sys"
-version = "4.1.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "76ee7a02da4d231650c7cea31349b889be2f45ddb3ef3032d2ec8185f6313fd2"
-dependencies = [
- "libc",
-]
-
 [[package]]
 name = "futures"
 version = "0.3.32"
@@ -841,6 +816,12 @@ version = "0.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
 
+[[package]]
+name = "hermit-abi"
+version = "0.5.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fc0fef456e4baa96da950455cd02c081ca953b141298e41db3fc7e36b1da849c"
+
 [[package]]
 name = "hex"
 version = "0.4.3"
@@ -1141,15 +1122,16 @@ dependencies = [
 
 [[package]]
 name = "indexer"
-version = "0.1.0"
+version = "0.2.0"
 dependencies = [
  "anyhow",
  "axum",
  "chrono",
- "notify",
+ "futures",
+ "image",
+ "jpeg-decoder",
+ "num_cpus",
  "parsers",
- "rand 0.8.5",
- "rayon",
  "reqwest",
  "serde",
  "serde_json",
@@ -1161,6 +1143,7 @@ dependencies = [
  "tracing-subscriber",
  "uuid",
  "walkdir",
+ "webp",
 ]
 
 [[package]]
@@ -1175,26 +1158,6 @@ dependencies = [
  "serde_core",
 ]
 
-[[package]]
-name = "inotify"
-version = "0.9.6"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f8069d3ec154eb856955c1c0fbffefbf5f3c40a104ec912d4797314c1801abff"
-dependencies = [
- "bitflags 1.3.2",
- "inotify-sys",
- "libc",
-]
-
-[[package]]
-name = "inotify-sys"
-version = "0.1.5"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e05c02b5e89bff3b946cedeca278abc628fe811e604f027c45a8aa3cf793d0eb"
-dependencies = [
- "libc",
-]
-
 [[package]]
 name = "inout"
 version = "0.1.4"
@@ -1221,12 +1184,62 @@ dependencies = [
  "serde",
 ]
 
+[[package]]
+name = "itertools"
+version = "0.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2b192c782037fadd9cfa75548310488aabdbf3d2da73885b31bd0abd03351285"
+dependencies = [
+ "either",
+]
+
 [[package]]
 name = "itoa"
 version = "1.0.17"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "92ecc6618181def0457392ccd0ee51198e065e016d1d527a7ac1b6dc7c1f09d2"
 
+[[package]]
+name = "jiff"
+version = "0.2.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1a3546dc96b6d42c5f24902af9e2538e82e39ad350b0c766eb3fbf2d8f3d8359"
+dependencies = [
+ "jiff-static",
+ "jiff-tzdb-platform",
+ "log",
+ "portable-atomic",
+ "portable-atomic-util",
+ "serde_core",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "jiff-static"
+version = "0.2.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2a8c8b344124222efd714b73bb41f8b5120b27a7cc1c75593a6ff768d9d05aa4"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.117",
+]
+
+[[package]]
+name = "jiff-tzdb"
+version = "0.1.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c900ef84826f1338a557697dc8fc601df9ca9af4ac137c7fb61d4c6f2dfd3076"
+
+[[package]]
+name = "jiff-tzdb-platform"
+version = "0.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "875a5a69ac2bab1a891711cf5eccbec1ce0341ea805560dcd90b7a2e925132e8"
+dependencies = [
+ "jiff-tzdb",
+]
+
 [[package]]
 name = "jobserver"
 version = "0.1.34"
@@ -1237,6 +1250,15 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "jpeg-decoder"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "00810f1d8b74be64b13dbf3db89ac67740615d6c891f0e7b6179326533011a07"
+dependencies = [
+ "rayon",
+]
+
 [[package]]
 name = "js-sys"
 version = "0.3.91"
@@ -1247,26 +1269,6 @@ dependencies = [
  "wasm-bindgen",
 ]
 
-[[package]]
-name = "kqueue"
-version = "1.1.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "eac30106d7dce88daf4a3fcb4879ea939476d5074a9b7ddd0fb97fa4bed5596a"
-dependencies = [
- "kqueue-sys",
- "libc",
-]
-
-[[package]]
-name = "kqueue-sys"
-version = "1.0.4"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ed9625ffda8729b85e45cf04090035ac368927b8cebc34898e7c120f52e4838b"
-dependencies = [
- "bitflags 1.3.2",
- "libc",
-]
-
 [[package]]
 name = "lazy_static"
 version = "1.5.0"
@@ -1288,6 +1290,16 @@ version = "0.2.182"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6800badb6cb2082ffd7b6a67e6125bb39f18782f793520caee8cb8846be06112"
 
+[[package]]
+name = "libloading"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "754ca22de805bb5744484a5b151a9e1a8e837d5dc232c2d7d8c2e3492edc8b60"
+dependencies = [
+ "cfg-if",
+ "windows-link",
+]
+
 [[package]]
 name = "libm"
 version = "0.2.16"
@@ -1300,7 +1312,7 @@ version = "0.1.14"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1744e39d1d6a9948f4f388969627434e31128196de472883b39f148769bfe30a"
 dependencies = [
- "bitflags 2.11.0",
+ "bitflags",
  "libc",
  "plain",
  "redox_syscall 0.7.3",
@@ -1349,25 +1361,33 @@ checksum = "5e5032e24019045c762d3c0f28f5b6b8bbf38563a65908389bf7978758920897"
 
 [[package]]
 name = "lopdf"
-version = "0.35.0"
+version = "0.39.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5c7c1d3350d071cb86987a6bcb205c7019a0eb70dcad92b454fec722cca8d68b"
+checksum = "f560f57dfb9142a02d673e137622fd515d4231e51feb8b4af28d92647d83f35b"
 dependencies = [
  "aes",
+ "bitflags",
  "cbc",
  "chrono",
+ "ecb",
  "encoding_rs",
  "flate2",
+ "getrandom 0.3.4",
  "indexmap",
  "itoa",
+ "jiff",
  "log",
  "md-5",
  "nom",
  "nom_locate",
+ "rand 0.9.2",
  "rangemap",
  "rayon",
+ "sha2",
+ "stringprep",
  "thiserror",
  "time",
+ "ttf-parser",
  "weezl",
 ]
 
@@ -1401,6 +1421,12 @@ version = "0.7.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0e7465ac9959cc2b1404e8e2367b43684a6d13790fe23056cc8c6c5a6b7bcb94"
 
+[[package]]
+name = "maybe-owned"
+version = "0.3.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4facc753ae494aeb6e3c22f839b158aebd4f9270f55cd3c79906c45476c47ab4"
+
 [[package]]
 name = "md-5"
 version = "0.10.6"
@@ -1433,12 +1459,6 @@ dependencies = [
  "unicase",
 ]
 
-[[package]]
-name = "minimal-lexical"
-version = "0.2.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "68354c5c6bd36d73ff3feceb05efa59b6acb7626617f4962be322a825e61f79a"
-
 [[package]]
 name = "miniz_oxide"
 version = "0.8.9"
@@ -1449,18 +1469,6 @@ dependencies = [
  "simd-adler32",
 ]
 
-[[package]]
-name = "mio"
-version = "0.8.11"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a4a650543ca06a924e8b371db273b2756685faae30f8487da1b56505a8f78b0c"
-dependencies = [
- "libc",
- "log",
- "wasi",
- "windows-sys 0.48.0",
-]
-
 [[package]]
 name = "mio"
 version = "1.1.1"
@@ -1483,45 +1491,31 @@ dependencies = [
 ]
 
 [[package]]
-name = "nom"
-version = "7.1.3"
+name = "natord"
+version = "1.0.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d273983c5a657a70a3e8f2a01329822f3b8c8172b73826411a55751e404a0a4a"
+checksum = "308d96db8debc727c3fd9744aac51751243420e46edf401010908da7f8d5e57c"
+
+[[package]]
+name = "nom"
+version = "8.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "df9761775871bdef83bee530e60050f7e54b1105350d6884eb0fb4f46c2f9405"
 dependencies = [
  "memchr",
- "minimal-lexical",
 ]
 
 [[package]]
 name = "nom_locate"
-version = "4.2.0"
+version = "5.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1e3c83c053b0713da60c5b8de47fe8e494fe3ece5267b2f23090a07a053ba8f3"
+checksum = "0b577e2d69827c4740cba2b52efaad1c4cc7c73042860b199710b3575c68438d"
 dependencies = [
  "bytecount",
  "memchr",
  "nom",
 ]
 
-[[package]]
-name = "notify"
-version = "6.1.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6205bd8bb1e454ad2e27422015fb5e4f2bcc7e08fa8f27058670d208324a4d2d"
-dependencies = [
- "bitflags 2.11.0",
- "crossbeam-channel",
- "filetime",
- "fsevent-sys",
- "inotify",
- "kqueue",
- "libc",
- "log",
- "mio 0.8.11",
- "walkdir",
- "windows-sys 0.48.0",
-]
-
 [[package]]
 name = "nu-ansi-term"
 version = "0.50.3"
@@ -1583,6 +1577,16 @@ dependencies = [
  "libm",
 ]
 
+[[package]]
+name = "num_cpus"
+version = "1.17.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "91df4bbde75afed763b708b7eee1e8e7651e02d97f6d5dd763e89367e957b23b"
+dependencies = [
+ "hermit-abi",
+ "libc",
+]
+
 [[package]]
 name = "once_cell"
 version = "1.21.3"
@@ -1620,14 +1624,18 @@ dependencies = [
 
 [[package]]
 name = "parsers"
-version = "0.1.0"
+version = "0.2.0"
 dependencies = [
  "anyhow",
+ "flate2",
+ "image",
  "lopdf",
+ "natord",
+ "pdfium-render",
  "regex",
- "uuid",
- "walkdir",
- "zip 2.4.2",
+ "tracing",
+ "unrar",
+ "zip 8.2.0",
 ]
 
 [[package]]
@@ -1641,6 +1649,32 @@ dependencies = [
  "subtle",
 ]
 
+[[package]]
+name = "pdfium-render"
+version = "0.8.37"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6553f6604a52b3203db7b4e9d51eb4dd193cf455af9e56d40cab6575b547b679"
+dependencies = [
+ "bitflags",
+ "bytemuck",
+ "bytes",
+ "chrono",
+ "console_error_panic_hook",
+ "console_log",
+ "image",
+ "itertools",
+ "js-sys",
+ "libloading",
+ "log",
+ "maybe-owned",
+ "once_cell",
+ "utf16string",
+ "vecmath",
+ "wasm-bindgen",
+ "wasm-bindgen-futures",
+ "web-sys",
+]
+
 [[package]]
 name = "pem-rfc7468"
 version = "0.7.0"
@@ -1668,6 +1702,12 @@ version = "0.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8b870d8c151b6f2fb93e84a13146138f05d02ed11c7e7c54f8826aaaf7c9f184"
 
+[[package]]
+name = "piston-float"
+version = "1.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ad78bf43dcf80e8f950c92b84f938a0fc7590b7f6866fbcbeca781609c115590"
+
 [[package]]
 name = "pkcs1"
 version = "0.7.5"
@@ -1707,13 +1747,28 @@ version = "0.18.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "60769b8b31b2a9f263dae2776c37b1b28ae246943cf719eb6946a1db05128a61"
 dependencies = [
- "bitflags 2.11.0",
+ "bitflags",
  "crc32fast",
  "fdeflate",
  "flate2",
  "miniz_oxide",
 ]
 
+[[package]]
+name = "portable-atomic"
+version = "1.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c33a9471896f1c69cecef8d20cbe2f7accd12527ce60845ff44c153bb2a21b49"
+
+[[package]]
+name = "portable-atomic-util"
+version = "0.2.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7a9db96d7fa8782dd8c15ce32ffe8680bbd1e978a43bf51a34d39483540495f5"
+dependencies = [
+ "portable-atomic",
+]
+
 [[package]]
 name = "potential_utf"
 version = "0.1.4"
@@ -1960,7 +2015,7 @@ version = "0.5.18"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ed2bf2547551a7053d6fdfafda3f938979645c44812fbfcda098faae3f1a362d"
 dependencies = [
- "bitflags 2.11.0",
+ "bitflags",
 ]
 
 [[package]]
@@ -1969,7 +2024,7 @@ version = "0.7.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6ce70a74e890531977d37e532c34d45e9055d2409ed08ddba14529471ed0be16"
 dependencies = [
- "bitflags 2.11.0",
+ "bitflags",
 ]
 
 [[package]]
@@ -2451,7 +2506,7 @@ checksum = "aa003f0038df784eb8fecbbac13affe3da23b45194bd57dba231c8f48199c526"
 dependencies = [
  "atoi",
  "base64",
- "bitflags 2.11.0",
+ "bitflags",
  "byteorder",
  "bytes",
  "chrono",
@@ -2495,7 +2550,7 @@ checksum = "db58fcd5a53cf07c184b154801ff91347e4c30d17a3562a635ff028ad5deda46"
 dependencies = [
  "atoi",
  "base64",
- "bitflags 2.11.0",
+ "bitflags",
  "byteorder",
  "chrono",
  "crc",
@@ -2571,7 +2626,7 @@ dependencies = [
 
 [[package]]
 name = "stripstream-core"
-version = "0.1.0"
+version = "0.2.0"
 dependencies = [
  "anyhow",
  "serde",
@@ -2717,7 +2772,7 @@ checksum = "27ad5e34374e03cfffefc301becb44e9dc3c17584f414349ebe29ed26661822d"
 dependencies = [
  "bytes",
  "libc",
- "mio 1.1.1",
+ "mio",
  "pin-project-lite",
  "signal-hook-registry",
  "socket2",
@@ -2793,7 +2848,7 @@ version = "0.6.8"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d4e6559d53cc268e5031cd8429d05415bc4cb4aefc4aa5d6cc35fbf5b924a1f8"
 dependencies = [
- "bitflags 2.11.0",
+ "bitflags",
  "bytes",
  "futures-util",
  "http",
@@ -2885,6 +2940,18 @@ version = "0.2.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e421abadd41a4225275504ea4d6566923418b7f05506fbc9c0fe86ba7396114b"
 
+[[package]]
+name = "ttf-parser"
+version = "0.25.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d2df906b07856748fa3f6e0ad0cbaa047052d4a7dd609e231c4f72cee8c36f31"
+
+[[package]]
+name = "typed-path"
+version = "0.12.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8e28f89b80c87b8fb0cf04ab448d5dd0dd0ade2f8891bae878de66a75a28600e"
+
 [[package]]
 name = "typenum"
 version = "1.19.0"
@@ -2930,6 +2997,29 @@ version = "0.2.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ebc1c04c71510c7f702b52b7c350734c9ff1295c464a03335b00bb84fc54f853"
 
+[[package]]
+name = "unrar"
+version = "0.5.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "92ec61343a630d2b50d13216dea5125e157d3fc180a7d3f447d22fe146b648fc"
+dependencies = [
+ "bitflags",
+ "regex",
+ "unrar_sys",
+ "widestring",
+]
+
+[[package]]
+name = "unrar_sys"
+version = "0.5.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8b77675b883cfbe6bf41e6b7a5cd6008e0a83ba497de3d96e41a064bbeead765"
+dependencies = [
+ "cc",
+ "libc",
+ "winapi",
+]
+
 [[package]]
 name = "untrusted"
 version = "0.9.0"
@@ -2948,6 +3038,15 @@ dependencies = [
  "serde",
 ]
 
+[[package]]
+name = "utf16string"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0b62a1e85e12d5d712bf47a85f426b73d303e2d00a90de5f3004df3596e9d216"
+dependencies = [
+ "byteorder",
+]
+
 [[package]]
 name = "utf8_iter"
 version = "1.0.4"
@@ -3018,6 +3117,15 @@ version = "0.2.15"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "accd4ea62f7bb7a82fe23066fb0957d48ef677f6eeb8215f372f52e48bb32426"
 
+[[package]]
+name = "vecmath"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "956ae1e0d85bca567dee1dcf87fb1ca2e792792f66f87dced8381f99cd91156a"
+dependencies = [
+ "piston-float",
+]
+
 [[package]]
 name = "version_check"
 version = "0.9.5"
@@ -3160,7 +3268,7 @@ version = "0.244.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "47b807c72e1bac69382b3a6fb3dbe8ea4c0ed87ff5629b8685ae6b9a611028fe"
 dependencies = [
- "bitflags 2.11.0",
+ "bitflags",
  "hashbrown 0.15.5",
  "indexmap",
  "semver",
@@ -3230,6 +3338,28 @@ dependencies = [
  "wasite",
 ]
 
+[[package]]
+name = "widestring"
+version = "1.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "72069c3113ab32ab29e5584db3c6ec55d416895e60715417b5b883a357c3e471"
+
+[[package]]
+name = "winapi"
+version = "0.3.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5c839a674fcd7a98952e593242ea400abe93992746761e38641405d28b00f419"
+dependencies = [
+ "winapi-i686-pc-windows-gnu",
+ "winapi-x86_64-pc-windows-gnu",
+]
+
+[[package]]
+name = "winapi-i686-pc-windows-gnu"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ac3b87c63620426dd9b991e5ce0329eff545bccbbb34f3be09ff6fb6ab51b7b6"
+
 [[package]]
 name = "winapi-util"
 version = "0.1.11"
@@ -3239,6 +3369,12 @@ dependencies = [
  "windows-sys 0.61.2",
 ]
 
+[[package]]
+name = "winapi-x86_64-pc-windows-gnu"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "712e227841d057c1ee1cd2fb22fa7e5a5461ae8e48fa2ca79ec42cfc1931183f"
+
 [[package]]
 name = "windows-core"
 version = "0.62.2"
@@ -3578,7 +3714,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9d66ea20e9553b30172b5e831994e35fbde2d165325bec84fc43dbf6f4eb9cb2"
 dependencies = [
  "anyhow",
- "bitflags 2.11.0",
+ "bitflags",
  "indexmap",
  "log",
  "serde",
@@ -3731,21 +3867,24 @@ dependencies = [
 
 [[package]]
 name = "zip"
-version = "2.4.2"
+version = "8.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "fabe6324e908f85a1c52063ce7aa26b68dcb7eb6dbc83a2d148403c9bc3eba50"
+checksum = "b680f2a0cd479b4cff6e1233c483fdead418106eae419dc60200ae9850f6d004"
 dependencies = [
- "arbitrary",
  "crc32fast",
- "crossbeam-utils",
- "displaydoc",
  "flate2",
  "indexmap",
  "memchr",
- "thiserror",
+ "typed-path",
  "zopfli",
 ]
 
+[[package]]
+name = "zlib-rs"
+version = "0.6.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3be3d40e40a133f9c916ee3f9f4fa2d9d63435b5fbe1bfc6d9dae0aa0ada1513"
+
 [[package]]
 name = "zmij"
 version = "1.0.21"

Cargo.toml

@@ -9,7 +9,7 @@ resolver = "2"
 
 [workspace.package]
 edition = "2021"
-version = "0.1.0"
+version = "0.2.0"
 license = "MIT"
 
 [workspace.dependencies]
@@ -19,6 +19,7 @@ axum = "0.7"
 base64 = "0.22"
 chrono = { version = "0.4", features = ["serde"] }
 image = { version = "0.25", default-features = false, features = ["jpeg", "png", "webp"] }
+jpeg-decoder = "0.3"
 lru = "0.12"
 rayon = "1.10"
 reqwest = { version = "0.12", default-features = false, features = ["json", "rustls-tls"] }
@@ -32,6 +33,11 @@ tower = { version = "0.5", features = ["limit"] }
 tracing = "0.1"
 tracing-subscriber = { version = "0.3", features = ["env-filter", "fmt"] }
 uuid = { version = "1.12", features = ["serde", "v4"] }
+natord = "1.0"
+num_cpus = "1.16"
+pdfium-render = { version = "0.8", default-features = false, features = ["pdfium_latest", "image_latest", "thread_safe"] }
+unrar = "0.5"
 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)
+- PostgreSQL (port 6432)
 - Meilisearch (port 7700)
-- API service (port 8080)
-- Indexer service (port 8081)
-- Backoffice web UI (port 8082)
+- 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
@@ -82,7 +82,7 @@ npm install
 npm run dev
 ```
 
-The backoffice will be available at http://localhost:3000
+The backoffice will be available at http://localhost:7082
 
 ## Features
 
@@ -111,24 +111,49 @@ The backoffice will be available at http://localhost:3000
 
 ## Environment Variables
 
-| 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` |
-| `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) | - |
-| `API_BOOTSTRAP_TOKEN` | Initial API admin token (required) | - |
-| `INDEXER_SCAN_INTERVAL_SECONDS` | Watcher scan interval | `5` |
-| `LIBRARIES_ROOT_PATH` | Path to libraries directory | `/libraries` |
+Variables marquées **required** doivent être définies. Les autres ont une valeur par défaut.
+
+### Partagées (API + Indexer)
+
+| Variable | Description | Défaut |
+|----------|-------------|--------|
+| `DATABASE_URL` | **required** — Connexion PostgreSQL | — |
+| `MEILI_URL` | **required** — URL Meilisearch | — |
+| `MEILI_MASTER_KEY` | **required** — Clé maître Meilisearch | — |
+
+### API
+
+| Variable | Description | Défaut |
+|----------|-------------|--------|
+| `API_BOOTSTRAP_TOKEN` | **required** — Token admin initial | — |
+| `API_LISTEN_ADDR` | Adresse d'écoute | `0.0.0.0:7080` |
+
+### Indexer
+
+| Variable | Description | Défaut |
+|----------|-------------|--------|
+| `INDEXER_LISTEN_ADDR` | Adresse d'écoute | `0.0.0.0:7081` |
+| `INDEXER_SCAN_INTERVAL_SECONDS` | Intervalle de scan du watcher | `5` |
+| `THUMBNAIL_ENABLED` | Activer la génération de thumbnails | `true` |
+| `THUMBNAIL_DIRECTORY` | Dossier de stockage des thumbnails | `/data/thumbnails` |
+| `THUMBNAIL_WIDTH` | Largeur max des thumbnails (px) | `300` |
+| `THUMBNAIL_HEIGHT` | Hauteur max des thumbnails (px) | `400` |
+| `THUMBNAIL_QUALITY` | Qualité WebP (0–100) | `80` |
+| `THUMBNAIL_FORMAT` | Format de sortie | `webp` |
+
+### Backoffice
+
+| Variable | Description | Défaut |
+|----------|-------------|--------|
+| `API_BOOTSTRAP_TOKEN` | **required** — Token d'accès à l'API | — |
+| `API_BASE_URL` | URL interne de l'API (dans le réseau Docker) | `http://api:7080` |
 
 ## API Documentation
 
 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
@@ -146,6 +171,99 @@ stripstream-librarian/
 └── .env                  # Environment configuration
 ```
 
+## Docker Registry
+
+Images are built and pushed to Docker Hub with the naming convention `docker.io/{owner}/stripstream-{service}`.
+
+### Publishing Images (Maintainers)
+
+To build and push all service images to the registry:
+
+```bash
+# Login to Docker Hub first
+docker login -u julienfroidefond32
+
+# Build and push all images
+./scripts/docker-push.sh
+```
+
+This script will:
+- Build images for `api`, `indexer`, and `backoffice`
+- Tag them with the current version (from `Cargo.toml`) and `latest`
+- Push to the registry
+
+### Using Published Images
+
+To use the pre-built images in your own `docker-compose.yml`:
+
+```yaml
+services:
+  postgres:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_DB: stripstream
+      POSTGRES_USER: stripstream
+      POSTGRES_PASSWORD: stripstream
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+
+  meilisearch:
+    image: getmeili/meilisearch:v1.12
+    environment:
+      MEILI_MASTER_KEY: your_meili_master_key   # required — change this
+
+  api:
+    image: julienfroidefond32/stripstream-api:latest
+    ports:
+      - "7080:7080"
+    volumes:
+      - ./libraries:/libraries
+      - ./data/thumbnails:/data/thumbnails
+    environment:
+      # --- Required ---
+      DATABASE_URL: postgres://stripstream:stripstream@postgres:5432/stripstream
+      MEILI_URL: http://meilisearch:7700
+      MEILI_MASTER_KEY: your_meili_master_key   # must match meilisearch above
+      API_BOOTSTRAP_TOKEN: your_bootstrap_token  # required — change this
+      # --- Optional (defaults shown) ---
+      # API_LISTEN_ADDR: 0.0.0.0:7080
+
+  indexer:
+    image: julienfroidefond32/stripstream-indexer:latest
+    ports:
+      - "7081:7081"
+    volumes:
+      - ./libraries:/libraries
+      - ./data/thumbnails:/data/thumbnails
+    environment:
+      # --- Required ---
+      DATABASE_URL: postgres://stripstream:stripstream@postgres:5432/stripstream
+      MEILI_URL: http://meilisearch:7700
+      MEILI_MASTER_KEY: your_meili_master_key   # must match meilisearch above
+      # --- Optional (defaults shown) ---
+      # INDEXER_LISTEN_ADDR: 0.0.0.0:7081
+      # INDEXER_SCAN_INTERVAL_SECONDS: 5
+      # THUMBNAIL_ENABLED: true
+      # THUMBNAIL_DIRECTORY: /data/thumbnails
+      # THUMBNAIL_WIDTH: 300
+      # THUMBNAIL_HEIGHT: 400
+      # THUMBNAIL_QUALITY: 80
+      # THUMBNAIL_FORMAT: webp
+
+  backoffice:
+    image: julienfroidefond32/stripstream-backoffice:latest
+    ports:
+      - "7082:7082"
+    environment:
+      # --- Required ---
+      API_BOOTSTRAP_TOKEN: your_bootstrap_token  # must match api above
+      # --- Optional (defaults shown) ---
+      # API_BASE_URL: http://api:7080
+
+volumes:
+  postgres_data:
+```
+
 ## License
 
 [Your License Here]

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

@@ -13,8 +13,10 @@ async-stream = "0.3"
 chrono.workspace = true
 futures = "0.3"
 image.workspace = true
+jpeg-decoder.workspace = true
 lru.workspace = true
 stripstream-core = { path = "../../crates/core" }
+parsers = { path = "../../crates/parsers" }
 rand.workspace = true
 tokio-stream = "0.1"
 reqwest.workspace = true
@@ -28,8 +30,6 @@ tower-http = { version = "0.6", features = ["cors"] }
 tracing.workspace = true
 tracing-subscriber.workspace = true
 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"
-walkdir = "2"
+webp.workspace = true

apps/api/Dockerfile

@@ -18,13 +18,34 @@ COPY crates/parsers/src crates/parsers/src
 
 # Build with sccache (cache persisted between builds via Docker cache mount)
 RUN --mount=type=cache,target=/sccache \
-    cargo build --release -p api
+    cargo build --release -p api && \
+    cargo install sqlx-cli --no-default-features --features postgres --locked
 
 FROM debian:bookworm-slim
-RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates wget unar poppler-utils locales && rm -rf /var/lib/apt/lists/*
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    ca-certificates wget locales postgresql-client \
+    && rm -rf /var/lib/apt/lists/*
 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
+
+# Download pdfium shared library (replaces pdftoppm subprocess)
+RUN ARCH=$(dpkg --print-architecture) && \
+    case "$ARCH" in \
+        amd64) PDFIUM_ARCH="linux-x64" ;; \
+        arm64) PDFIUM_ARCH="linux-arm64" ;; \
+        *) echo "Unsupported arch: $ARCH" && exit 1 ;; \
+    esac && \
+    wget -q "https://github.com/bblanchon/pdfium-binaries/releases/latest/download/pdfium-${PDFIUM_ARCH}.tgz" -O /tmp/pdfium.tgz && \
+    tar -xzf /tmp/pdfium.tgz -C /tmp && \
+    cp /tmp/lib/libpdfium.so /usr/local/lib/ && \
+    rm -rf /tmp/pdfium.tgz /tmp/lib /tmp/include && \
+    ldconfig
 COPY --from=builder /app/target/release/api /usr/local/bin/api
-EXPOSE 8080
-CMD ["/usr/local/bin/api"]
+COPY --from=builder /usr/local/cargo/bin/sqlx /usr/local/bin/sqlx
+COPY infra/migrations /app/migrations
+COPY apps/api/entrypoint.sh /usr/local/bin/entrypoint.sh
+RUN chmod +x /usr/local/bin/entrypoint.sh
+EXPOSE 7080
+CMD ["/usr/local/bin/entrypoint.sh"]

apps/api/entrypoint.sh

@@ -0,0 +1,63 @@
+#!/bin/sh
+set -e
+
+# psql requires "postgresql://" but Rust/sqlx accepts both "postgres://" and "postgresql://"
+PSQL_URL=$(echo "$DATABASE_URL" | sed 's|^postgres://|postgresql://|')
+
+# Check 1: does the old schema exist (index_jobs table)?
+HAS_OLD_TABLES=$(psql "$PSQL_URL" -tAc \
+    "SELECT EXISTS(SELECT 1 FROM information_schema.tables WHERE table_name='index_jobs')::text" \
+    2>/dev/null || echo "false")
+
+# Check 2: is sqlx tracking present and non-empty?
+HAS_SQLX_TABLE=$(psql "$PSQL_URL" -tAc \
+    "SELECT EXISTS(SELECT 1 FROM information_schema.tables WHERE table_name='_sqlx_migrations')::text" \
+    2>/dev/null || echo "false")
+
+if [ "$HAS_SQLX_TABLE" = "true" ]; then
+    HAS_SQLX_ROWS=$(psql "$PSQL_URL" -tAc \
+        "SELECT EXISTS(SELECT 1 FROM _sqlx_migrations LIMIT 1)::text" \
+        2>/dev/null || echo "false")
+else
+    HAS_SQLX_ROWS="false"
+fi
+
+echo "==> Migration check: old_tables=$HAS_OLD_TABLES sqlx_table=$HAS_SQLX_TABLE sqlx_rows=$HAS_SQLX_ROWS"
+
+if [ "$HAS_OLD_TABLES" = "true" ] && [ "$HAS_SQLX_ROWS" = "false" ]; then
+    echo "==> Upgrade from pre-sqlx migration system detected: creating baseline..."
+
+    psql "$PSQL_URL" -c "
+        CREATE TABLE IF NOT EXISTS _sqlx_migrations (
+            version          BIGINT      PRIMARY KEY,
+            description      TEXT        NOT NULL,
+            installed_on     TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+            success          BOOLEAN     NOT NULL,
+            checksum         BYTEA       NOT NULL,
+            execution_time   BIGINT      NOT NULL
+        )
+    "
+
+    for f in /app/migrations/*.sql; do
+        filename=$(basename "$f")
+        # Strip leading zeros to get the integer version (e.g. "0005" -> "5")
+        version=$(echo "$filename" | sed 's/^0*//' | cut -d'_' -f1)
+        description=$(echo "$filename" | sed 's/^[0-9]*_//' | sed 's/\.sql$//')
+        checksum=$(sha384sum "$f" | awk '{print $1}')
+
+        psql "$PSQL_URL" -c "
+            INSERT INTO _sqlx_migrations (version, description, installed_on, success, checksum, execution_time)
+            VALUES ($version, '$description', NOW(), TRUE, decode('$checksum', 'hex'), 0)
+            ON CONFLICT (version) DO NOTHING
+        "
+        echo "    baselined: $filename"
+    done
+
+    echo "==> Baseline complete."
+fi
+
+echo "==> Running migrations..."
+sqlx migrate run --source /app/migrations
+
+echo "==> Starting API..."
+exec /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 {
@@ -94,11 +94,15 @@ async fn authenticate(state: &AppState, token: &str) -> Result<Scope, ApiError>
 }
 
 fn parse_prefix(token: &str) -> Option<&str> {
-    let mut parts = token.split('_');
-    let namespace = parts.next()?;
-    let prefix = parts.next()?;
-    let secret = parts.next()?;
-    if namespace != "stl" || secret.is_empty() || prefix.len() < 6 {
+    // Format: stl_{8-char prefix}_{secret}
+    // Base64 URL_SAFE peut contenir '_', donc on ne peut pas splitter aveuglément
+    let rest = token.strip_prefix("stl_")?;
+    if rest.len() < 10 {
+        // 8 (prefix) + 1 ('_') + 1 (secret min)
+        return None;
+    }
+    let prefix = &rest[..8];
+    if rest.as_bytes().get(8) != Some(&b'_') {
         return None;
     }
     Some(prefix)

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 {
@@ -13,10 +13,14 @@ pub struct ListBooksQuery {
     pub library_id: Option<Uuid>,
     #[schema(value_type = Option<String>)]
     pub kind: Option<String>,
+    #[schema(value_type = Option<String>, example = "cbz")]
+    pub format: Option<String>,
     #[schema(value_type = Option<String>)]
     pub series: Option<String>,
-    #[schema(value_type = Option<String>)]
-    pub cursor: Option<Uuid>,
+    #[schema(value_type = Option<String>, example = "unread,reading")]
+    pub reading_status: Option<String>,
+    #[schema(value_type = Option<i64>, example = 1)]
+    pub page: Option<i64>,
     #[schema(value_type = Option<i64>, example = 50)]
     pub limit: Option<i64>,
 }
@@ -28,6 +32,7 @@ pub struct BookItem {
     #[schema(value_type = String)]
     pub library_id: Uuid,
     pub kind: String,
+    pub format: Option<String>,
     pub title: String,
     pub author: Option<String>,
     pub series: Option<String>,
@@ -37,13 +42,19 @@ pub struct BookItem {
     pub thumbnail_url: Option<String>,
     #[schema(value_type = String)]
     pub updated_at: DateTime<Utc>,
+    /// 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>>,
 }
 
 #[derive(Serialize, ToSchema)]
 pub struct BooksPage {
     pub items: Vec<BookItem>,
-    #[schema(value_type = Option<String>)]
-    pub next_cursor: Option<Uuid>,
+    pub total: i64,
+    pub page: i64,
+    pub limit: i64,
 }
 
 #[derive(Serialize, ToSchema)]
@@ -63,6 +74,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
@@ -74,8 +90,9 @@ pub struct BookDetails {
         ("library_id" = Option<String>, Query, description = "Filter by library ID"),
         ("kind" = Option<String>, Query, description = "Filter by book kind (cbz, cbr, pdf)"),
         ("series" = Option<String>, Query, description = "Filter by series name (use 'unclassified' for books without series)"),
-        ("cursor" = Option<String>, Query, description = "Cursor for pagination"),
-        ("limit" = Option<i64>, Query, description = "Max items to return (max 200)"),
+        ("reading_status" = Option<String>, Query, description = "Filter by reading status, comma-separated (e.g. 'unread,reading')"),
+        ("page" = Option<i64>, Query, description = "Page number (1-indexed, default 1)"),
+        ("limit" = Option<i64>, Query, description = "Items per page (max 200, default 50)"),
     ),
     responses(
         (status = 200, body = BooksPage),
@@ -88,61 +105,99 @@ pub async fn list_books(
     Query(query): Query<ListBooksQuery>,
 ) -> Result<Json<BooksPage>, ApiError> {
     let limit = query.limit.unwrap_or(50).clamp(1, 200);
+    let page = query.page.unwrap_or(1).max(1);
+    let offset = (page - 1) * limit;
 
-    // Build series filter condition
-    let series_condition = match query.series.as_deref() {
-        Some("unclassified") => "AND (series IS NULL OR series = '')",
-        Some(_series_name) => "AND series = $5",
-        None => "",
+    // Parse reading_status CSV → Vec<String>
+    let reading_statuses: Option<Vec<String>> = query.reading_status.as_deref().map(|s| {
+        s.split(',').map(|v| v.trim().to_string()).filter(|v| !v.is_empty()).collect()
+    });
+
+    // Conditions partagées COUNT et DATA — $1=library_id $2=kind $3=format, puis optionnels
+    let mut p: usize = 3;
+    let series_cond = match query.series.as_deref() {
+        Some("unclassified") => "AND (b.series IS NULL OR b.series = '')".to_string(),
+        Some(_) => { p += 1; format!("AND b.series = ${p}") }
+        None => String::new(),
     };
+    let rs_cond = if reading_statuses.is_some() {
+        p += 1; format!("AND COALESCE(brp.status, 'unread') = ANY(${p})")
+    } else { String::new() };
 
-    let sql = format!(
-        r#"
-        SELECT id, library_id, kind, title, author, series, volume, language, page_count, thumbnail_path, updated_at
-        FROM books
-        WHERE ($1::uuid IS NULL OR library_id = $1)
-          AND ($2::text IS NULL OR kind = $2)
-          AND ($3::uuid IS NULL OR id > $3)
-          {}
-        ORDER BY 
-            -- Extract text part before numbers (case insensitive)
-            REGEXP_REPLACE(LOWER(title), '[0-9]+', '', 'g'),
-            -- Extract first number group and convert to integer for numeric sort
-            COALESCE(
-                (REGEXP_MATCH(LOWER(title), '\d+'))[1]::int,
-                0
-            ),
-            -- Then by full title as fallback
-            title ASC
-        LIMIT $4
-        "#,
-        series_condition
+    let count_sql = format!(
+        r#"SELECT COUNT(*) FROM books b
+           LEFT JOIN book_reading_progress brp ON brp.book_id = b.id
+           WHERE ($1::uuid IS NULL OR b.library_id = $1)
+             AND ($2::text IS NULL OR b.kind = $2)
+             AND ($3::text IS NULL OR b.format = $3)
+             {series_cond}
+             {rs_cond}"#
     );
 
-    let mut query_builder = sqlx::query(&sql)
+    // DATA: mêmes params filtre, puis $N+1=limit $N+2=offset
+    let limit_p = p + 1;
+    let offset_p = p + 2;
+    let data_sql = format!(
+        r#"
+        SELECT b.id, b.library_id, b.kind, b.format, b.title, b.author, b.series, b.volume, b.language, b.page_count, b.thumbnail_path, b.updated_at,
+               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 book_reading_progress brp ON brp.book_id = b.id
+        WHERE ($1::uuid IS NULL OR b.library_id = $1)
+          AND ($2::text IS NULL OR b.kind = $2)
+          AND ($3::text IS NULL OR b.format = $3)
+          {series_cond}
+          {rs_cond}
+        ORDER BY
+            REGEXP_REPLACE(LOWER(b.title), '[0-9]+', '', 'g'),
+            COALESCE(
+                (REGEXP_MATCH(LOWER(b.title), '\d+'))[1]::int,
+                0
+            ),
+            b.title ASC
+        LIMIT ${limit_p} OFFSET ${offset_p}
+        "#
+    );
+
+    let mut count_builder = sqlx::query(&count_sql)
         .bind(query.library_id)
         .bind(query.kind.as_deref())
-        .bind(query.cursor)
-        .bind(limit + 1);
+        .bind(query.format.as_deref());
+    let mut data_builder = sqlx::query(&data_sql)
+        .bind(query.library_id)
+        .bind(query.kind.as_deref())
+        .bind(query.format.as_deref());
 
-    // Bind series parameter if it's not unclassified
-    if let Some(series) = query.series.as_deref() {
-        if series != "unclassified" {
-            query_builder = query_builder.bind(series);
+    if let Some(s) = query.series.as_deref() {
+        if s != "unclassified" {
+            count_builder = count_builder.bind(s);
+            data_builder = data_builder.bind(s);
         }
     }
+    if let Some(ref statuses) = reading_statuses {
+        count_builder = count_builder.bind(statuses.clone());
+        data_builder = data_builder.bind(statuses.clone());
+    }
 
-    let rows = query_builder.fetch_all(&state.pool).await?;
+    data_builder = data_builder.bind(limit).bind(offset);
+
+    let (count_row, rows) = tokio::try_join!(
+        count_builder.fetch_one(&state.pool),
+        data_builder.fetch_all(&state.pool),
+    )?;
+    let total: i64 = count_row.get(0);
 
     let mut items: Vec<BookItem> = rows
         .iter()
-        .take(limit as usize)
         .map(|row| {
             let thumbnail_path: Option<String> = row.get("thumbnail_path");
             BookItem {
                 id: row.get("id"),
                 library_id: row.get("library_id"),
                 kind: row.get("kind"),
+                format: row.get("format"),
                 title: row.get("title"),
                 author: row.get("author"),
                 series: row.get("series"),
@@ -151,19 +206,18 @@ pub async fn list_books(
                 page_count: row.get("page_count"),
                 thumbnail_url: thumbnail_path.map(|_p| format!("/books/{}/thumbnail", row.get::<Uuid, _>("id"))),
                 updated_at: row.get("updated_at"),
+                reading_status: row.get("reading_status"),
+                reading_current_page: row.get("reading_current_page"),
+                reading_last_read_at: row.get("reading_last_read_at"),
             }
         })
         .collect();
 
-    let next_cursor = if rows.len() > limit as usize {
-        items.last().map(|b| b.id)
-    } else {
-        None
-    };
-
     Ok(Json(BooksPage {
         items: std::mem::take(&mut items),
-        next_cursor,
+        total,
+        page,
+        limit,
     }))
 }
 
@@ -189,7 +243,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 +255,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 +279,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"),
     }))
 }
 
@@ -228,21 +289,29 @@ pub async fn get_book(
 pub struct SeriesItem {
     pub name: String,
     pub book_count: i64,
+    pub books_read_count: i64,
     #[schema(value_type = String)]
     pub first_book_id: Uuid,
+    #[schema(value_type = String)]
+    pub library_id: Uuid,
 }
 
 #[derive(Serialize, ToSchema)]
 pub struct SeriesPage {
     pub items: Vec<SeriesItem>,
-    #[schema(value_type = Option<String>)]
-    pub next_cursor: Option<String>,
+    pub total: i64,
+    pub page: i64,
+    pub limit: i64,
 }
 
 #[derive(Deserialize, ToSchema)]
 pub struct ListSeriesQuery {
-    #[schema(value_type = Option<String>)]
-    pub cursor: Option<String>,
+    #[schema(value_type = Option<String>, example = "dragon")]
+    pub q: Option<String>,
+    #[schema(value_type = Option<String>, example = "unread,reading")]
+    pub reading_status: Option<String>,
+    #[schema(value_type = Option<i64>, example = 1)]
+    pub page: Option<i64>,
     #[schema(value_type = Option<i64>, example = 50)]
     pub limit: Option<i64>,
 }
@@ -254,8 +323,10 @@ pub struct ListSeriesQuery {
     tag = "books",
     params(
         ("library_id" = String, Path, description = "Library UUID"),
-        ("cursor" = Option<String>, Query, description = "Cursor for pagination (series name)"),
-        ("limit" = Option<i64>, Query, description = "Max items to return (max 200)"),
+        ("q" = Option<String>, Query, description = "Filter by series name (case-insensitive, partial match)"),
+        ("reading_status" = Option<String>, Query, description = "Filter by reading status, comma-separated (e.g. 'unread,reading')"),
+        ("page" = Option<i64>, Query, description = "Page number (1-indexed, default 1)"),
+        ("limit" = Option<i64>, Query, description = "Items per page (max 200, default 50)"),
     ),
     responses(
         (status = 200, body = SeriesPage),
@@ -269,14 +340,59 @@ pub async fn list_series(
     Query(query): Query<ListSeriesQuery>,
 ) -> Result<Json<SeriesPage>, ApiError> {
     let limit = query.limit.unwrap_or(50).clamp(1, 200);
+    let page = query.page.unwrap_or(1).max(1);
+    let offset = (page - 1) * limit;
 
-    let rows = sqlx::query(
+    let reading_statuses: Option<Vec<String>> = query.reading_status.as_deref().map(|s| {
+        s.split(',').map(|v| v.trim().to_string()).filter(|v| !v.is_empty()).collect()
+    });
+
+    let series_status_expr = r#"CASE
+              WHEN sc.books_read_count = sc.book_count THEN 'read'
+              WHEN sc.books_read_count = 0 THEN 'unread'
+              ELSE 'reading'
+           END"#;
+
+    // Paramètres dynamiques — $1 = library_id fixe, puis optionnels dans l'ordre
+    let mut p: usize = 1;
+
+    let q_cond = if query.q.is_some() {
+        p += 1; format!("AND sc.name ILIKE ${p}")
+    } else { String::new() };
+
+    let count_rs_cond = if reading_statuses.is_some() {
+        p += 1; format!("AND {series_status_expr} = ANY(${p})")
+    } else { String::new() };
+
+    // q_cond et count_rs_cond partagent le même p — le count_sql les réutilise directement
+    let count_sql = format!(
+        r#"
+        WITH sorted_books AS (
+            SELECT COALESCE(NULLIF(series, ''), 'unclassified') as name, id
+            FROM books WHERE library_id = $1
+        ),
+        series_counts AS (
+            SELECT sb.name,
+                COUNT(*) as book_count,
+                COUNT(brp.book_id) FILTER (WHERE brp.status = 'read') as books_read_count
+            FROM sorted_books sb
+            LEFT JOIN book_reading_progress brp ON brp.book_id = sb.id
+            GROUP BY sb.name
+        )
+        SELECT COUNT(*) FROM series_counts sc WHERE TRUE {q_cond} {count_rs_cond}
+        "#
+    );
+
+    // DATA: mêmes params dans le même ordre, puis limit/offset à la fin
+    let limit_p = p + 1;
+    let offset_p = p + 2;
+
+    let data_sql = format!(
         r#"
         WITH sorted_books AS (
             SELECT
                 COALESCE(NULLIF(series, ''), 'unclassified') as name,
                 id,
-                -- Natural sort order for books within series
                 ROW_NUMBER() OVER (
                     PARTITION BY COALESCE(NULLIF(series, ''), 'unclassified')
                     ORDER BY
@@ -289,64 +405,565 @@ pub async fn list_series(
         ),
         series_counts AS (
             SELECT
-                name,
-                COUNT(*) as book_count
-            FROM sorted_books
-            GROUP BY name
+                sb.name,
+                COUNT(*) as book_count,
+                COUNT(brp.book_id) FILTER (WHERE brp.status = 'read') as books_read_count
+            FROM sorted_books sb
+            LEFT JOIN book_reading_progress brp ON brp.book_id = sb.id
+            GROUP BY sb.name
         )
         SELECT
             sc.name,
             sc.book_count,
+            sc.books_read_count,
             sb.id as first_book_id
         FROM series_counts sc
         JOIN sorted_books sb ON sb.name = sc.name AND sb.rn = 1
-        WHERE ($2::text IS NULL OR sc.name > $2)
+        WHERE TRUE
+          {q_cond}
+          {count_rs_cond}
         ORDER BY
-            -- Natural sort: extract text part before numbers
             REGEXP_REPLACE(LOWER(sc.name), '[0-9]+', '', 'g'),
-            -- Extract first number group and convert to integer
             COALESCE(
                 (REGEXP_MATCH(LOWER(sc.name), '\d+'))[1]::int,
                 0
             ),
             sc.name ASC
-        LIMIT $3
-        "#,
-    )
-    .bind(library_id)
-    .bind(query.cursor.as_deref())
-    .bind(limit + 1)
-    .fetch_all(&state.pool)
-    .await?;
+        LIMIT ${limit_p} OFFSET ${offset_p}
+        "#
+    );
+
+    let q_pattern = query.q.as_deref().map(|q| format!("%{}%", q));
+
+    let mut count_builder = sqlx::query(&count_sql).bind(library_id);
+    let mut data_builder = sqlx::query(&data_sql).bind(library_id);
+
+    if let Some(ref pat) = q_pattern {
+        count_builder = count_builder.bind(pat);
+        data_builder = data_builder.bind(pat);
+    }
+    if let Some(ref statuses) = reading_statuses {
+        count_builder = count_builder.bind(statuses.clone());
+        data_builder = data_builder.bind(statuses.clone());
+    }
+
+    data_builder = data_builder.bind(limit).bind(offset);
+
+    let (count_row, rows) = tokio::try_join!(
+        count_builder.fetch_one(&state.pool),
+        data_builder.fetch_all(&state.pool),
+    )?;
+    let total: i64 = count_row.get(0);
 
     let mut items: Vec<SeriesItem> = rows
         .iter()
-        .take(limit as usize)
         .map(|row| SeriesItem {
             name: row.get("name"),
             book_count: row.get("book_count"),
+            books_read_count: row.get("books_read_count"),
             first_book_id: row.get("first_book_id"),
+            library_id,
         })
         .collect();
 
-    let next_cursor = if rows.len() > limit as usize {
-        items.last().map(|s| s.name.clone())
-    } else {
-        None
-    };
-
     Ok(Json(SeriesPage {
         items: std::mem::take(&mut items),
-        next_cursor,
+        total,
+        page,
+        limit,
     }))
 }
 
+#[derive(Deserialize, ToSchema)]
+pub struct ListAllSeriesQuery {
+    #[schema(value_type = Option<String>, example = "dragon")]
+    pub q: Option<String>,
+    #[schema(value_type = Option<String>)]
+    pub library_id: Option<Uuid>,
+    #[schema(value_type = Option<String>, example = "unread,reading")]
+    pub reading_status: Option<String>,
+    #[schema(value_type = Option<i64>, example = 1)]
+    pub page: Option<i64>,
+    #[schema(value_type = Option<i64>, example = 50)]
+    pub limit: Option<i64>,
+}
+
+/// List all series across libraries with optional filtering and pagination
+#[utoipa::path(
+    get,
+    path = "/series",
+    tag = "books",
+    params(
+        ("q" = Option<String>, Query, description = "Filter by series name (case-insensitive, partial match)"),
+        ("library_id" = Option<String>, Query, description = "Filter by library ID"),
+        ("reading_status" = Option<String>, Query, description = "Filter by reading status, comma-separated (e.g. 'unread,reading')"),
+        ("page" = Option<i64>, Query, description = "Page number (1-indexed, default 1)"),
+        ("limit" = Option<i64>, Query, description = "Items per page (max 200, default 50)"),
+    ),
+    responses(
+        (status = 200, body = SeriesPage),
+        (status = 401, description = "Unauthorized"),
+    ),
+    security(("Bearer" = []))
+)]
+pub async fn list_all_series(
+    State(state): State<AppState>,
+    Query(query): Query<ListAllSeriesQuery>,
+) -> Result<Json<SeriesPage>, ApiError> {
+    let limit = query.limit.unwrap_or(50).clamp(1, 200);
+    let page = query.page.unwrap_or(1).max(1);
+    let offset = (page - 1) * limit;
+
+    let reading_statuses: Option<Vec<String>> = query.reading_status.as_deref().map(|s| {
+        s.split(',').map(|v| v.trim().to_string()).filter(|v| !v.is_empty()).collect()
+    });
+
+    let series_status_expr = r#"CASE
+              WHEN sc.books_read_count = sc.book_count THEN 'read'
+              WHEN sc.books_read_count = 0 THEN 'unread'
+              ELSE 'reading'
+           END"#;
+
+    let mut p: usize = 0;
+
+    let lib_cond = if query.library_id.is_some() {
+        p += 1; format!("WHERE library_id = ${p}")
+    } else {
+        "WHERE TRUE".to_string()
+    };
+
+    let q_cond = if query.q.is_some() {
+        p += 1; format!("AND sc.name ILIKE ${p}")
+    } else { String::new() };
+
+    let rs_cond = if reading_statuses.is_some() {
+        p += 1; format!("AND {series_status_expr} = ANY(${p})")
+    } else { String::new() };
+
+    let count_sql = format!(
+        r#"
+        WITH sorted_books AS (
+            SELECT COALESCE(NULLIF(series, ''), 'unclassified') as name, id
+            FROM books {lib_cond}
+        ),
+        series_counts AS (
+            SELECT sb.name,
+                COUNT(*) as book_count,
+                COUNT(brp.book_id) FILTER (WHERE brp.status = 'read') as books_read_count
+            FROM sorted_books sb
+            LEFT JOIN book_reading_progress brp ON brp.book_id = sb.id
+            GROUP BY sb.name
+        )
+        SELECT COUNT(*) FROM series_counts sc WHERE TRUE {q_cond} {rs_cond}
+        "#
+    );
+
+    let limit_p = p + 1;
+    let offset_p = p + 2;
+
+    let data_sql = format!(
+        r#"
+        WITH sorted_books AS (
+            SELECT
+                COALESCE(NULLIF(series, ''), 'unclassified') as name,
+                id,
+                library_id,
+                ROW_NUMBER() OVER (
+                    PARTITION BY COALESCE(NULLIF(series, ''), 'unclassified')
+                    ORDER BY
+                        REGEXP_REPLACE(LOWER(title), '[0-9]+', '', 'g'),
+                        COALESCE((REGEXP_MATCH(LOWER(title), '\d+'))[1]::int, 0),
+                        title ASC
+                ) as rn
+            FROM books
+            {lib_cond}
+        ),
+        series_counts AS (
+            SELECT
+                sb.name,
+                COUNT(*) as book_count,
+                COUNT(brp.book_id) FILTER (WHERE brp.status = 'read') as books_read_count
+            FROM sorted_books sb
+            LEFT JOIN book_reading_progress brp ON brp.book_id = sb.id
+            GROUP BY sb.name
+        )
+        SELECT
+            sc.name,
+            sc.book_count,
+            sc.books_read_count,
+            sb.id as first_book_id,
+            sb.library_id
+        FROM series_counts sc
+        JOIN sorted_books sb ON sb.name = sc.name AND sb.rn = 1
+        WHERE TRUE
+          {q_cond}
+          {rs_cond}
+        ORDER BY
+            REGEXP_REPLACE(LOWER(sc.name), '[0-9]+', '', 'g'),
+            COALESCE(
+                (REGEXP_MATCH(LOWER(sc.name), '\d+'))[1]::int,
+                0
+            ),
+            sc.name ASC
+        LIMIT ${limit_p} OFFSET ${offset_p}
+        "#
+    );
+
+    let q_pattern = query.q.as_deref().map(|q| format!("%{}%", q));
+
+    let mut count_builder = sqlx::query(&count_sql);
+    let mut data_builder = sqlx::query(&data_sql);
+
+    if let Some(lib_id) = query.library_id {
+        count_builder = count_builder.bind(lib_id);
+        data_builder = data_builder.bind(lib_id);
+    }
+    if let Some(ref pat) = q_pattern {
+        count_builder = count_builder.bind(pat);
+        data_builder = data_builder.bind(pat);
+    }
+    if let Some(ref statuses) = reading_statuses {
+        count_builder = count_builder.bind(statuses.clone());
+        data_builder = data_builder.bind(statuses.clone());
+    }
+
+    data_builder = data_builder.bind(limit).bind(offset);
+
+    let (count_row, rows) = tokio::try_join!(
+        count_builder.fetch_one(&state.pool),
+        data_builder.fetch_all(&state.pool),
+    )?;
+    let total: i64 = count_row.get(0);
+
+    let items: Vec<SeriesItem> = rows
+        .iter()
+        .map(|row| SeriesItem {
+            name: row.get("name"),
+            book_count: row.get("book_count"),
+            books_read_count: row.get("books_read_count"),
+            first_book_id: row.get("first_book_id"),
+            library_id: row.get("library_id"),
+        })
+        .collect();
+
+    Ok(Json(SeriesPage {
+        items,
+        total,
+        page,
+        limit,
+    }))
+}
+
+#[derive(Deserialize, ToSchema)]
+pub struct OngoingQuery {
+    #[schema(value_type = Option<i64>, example = 10)]
+    pub limit: Option<i64>,
+}
+
+/// List ongoing series (partially read, sorted by most recent activity)
+#[utoipa::path(
+    get,
+    path = "/series/ongoing",
+    tag = "books",
+    params(
+        ("limit" = Option<i64>, Query, description = "Max items to return (default 10, max 50)"),
+    ),
+    responses(
+        (status = 200, body = Vec<SeriesItem>),
+        (status = 401, description = "Unauthorized"),
+    ),
+    security(("Bearer" = []))
+)]
+pub async fn ongoing_series(
+    State(state): State<AppState>,
+    Query(query): Query<OngoingQuery>,
+) -> Result<Json<Vec<SeriesItem>>, ApiError> {
+    let limit = query.limit.unwrap_or(10).clamp(1, 50);
+
+    let rows = sqlx::query(
+        r#"
+        WITH series_stats AS (
+            SELECT
+                COALESCE(NULLIF(b.series, ''), 'unclassified') AS name,
+                COUNT(*) AS book_count,
+                COUNT(brp.book_id) FILTER (WHERE brp.status = 'read') AS books_read_count,
+                MAX(brp.last_read_at) AS last_read_at
+            FROM books b
+            LEFT JOIN book_reading_progress brp ON brp.book_id = b.id
+            GROUP BY COALESCE(NULLIF(b.series, ''), 'unclassified')
+            HAVING (
+                COUNT(brp.book_id) FILTER (WHERE brp.status IN ('read', 'reading')) > 0
+                AND COUNT(brp.book_id) FILTER (WHERE brp.status = 'read') < COUNT(*)
+            )
+        ),
+        first_books AS (
+            SELECT
+                COALESCE(NULLIF(series, ''), 'unclassified') AS name,
+                id,
+                library_id,
+                ROW_NUMBER() OVER (
+                    PARTITION BY COALESCE(NULLIF(series, ''), 'unclassified')
+                    ORDER BY
+                        REGEXP_REPLACE(LOWER(title), '[0-9]+', '', 'g'),
+                        COALESCE((REGEXP_MATCH(LOWER(title), '\d+'))[1]::int, 0),
+                        title ASC
+                ) AS rn
+            FROM books
+        )
+        SELECT ss.name, ss.book_count, ss.books_read_count, fb.id AS first_book_id, fb.library_id
+        FROM series_stats ss
+        JOIN first_books fb ON fb.name = ss.name AND fb.rn = 1
+        ORDER BY ss.last_read_at DESC NULLS LAST
+        LIMIT $1
+        "#,
+    )
+    .bind(limit)
+    .fetch_all(&state.pool)
+    .await?;
+
+    let items: Vec<SeriesItem> = rows
+        .iter()
+        .map(|row| SeriesItem {
+            name: row.get("name"),
+            book_count: row.get("book_count"),
+            books_read_count: row.get("books_read_count"),
+            first_book_id: row.get("first_book_id"),
+            library_id: row.get("library_id"),
+        })
+        .collect();
+
+    Ok(Json(items))
+}
+
+/// List next unread book for each ongoing series (sorted by most recent activity)
+#[utoipa::path(
+    get,
+    path = "/books/ongoing",
+    tag = "books",
+    params(
+        ("limit" = Option<i64>, Query, description = "Max items to return (default 10, max 50)"),
+    ),
+    responses(
+        (status = 200, body = Vec<BookItem>),
+        (status = 401, description = "Unauthorized"),
+    ),
+    security(("Bearer" = []))
+)]
+pub async fn ongoing_books(
+    State(state): State<AppState>,
+    Query(query): Query<OngoingQuery>,
+) -> Result<Json<Vec<BookItem>>, ApiError> {
+    let limit = query.limit.unwrap_or(10).clamp(1, 50);
+
+    let rows = sqlx::query(
+        r#"
+        WITH ongoing_series AS (
+            SELECT
+                COALESCE(NULLIF(b.series, ''), 'unclassified') AS name,
+                MAX(brp.last_read_at) AS series_last_read_at
+            FROM books b
+            LEFT JOIN book_reading_progress brp ON brp.book_id = b.id
+            GROUP BY COALESCE(NULLIF(b.series, ''), 'unclassified')
+            HAVING (
+                COUNT(brp.book_id) FILTER (WHERE brp.status IN ('read', 'reading')) > 0
+                AND COUNT(brp.book_id) FILTER (WHERE brp.status = 'read') < COUNT(*)
+            )
+        ),
+        next_books AS (
+            SELECT
+                b.id, b.library_id, b.kind, b.format, b.title, b.author, b.series, b.volume,
+                b.language, b.page_count, b.thumbnail_path, b.updated_at,
+                COALESCE(brp.status, 'unread') AS reading_status,
+                brp.current_page AS reading_current_page,
+                brp.last_read_at AS reading_last_read_at,
+                os.series_last_read_at,
+                ROW_NUMBER() OVER (
+                    PARTITION BY COALESCE(NULLIF(b.series, ''), 'unclassified')
+                    ORDER BY b.volume NULLS LAST, b.title
+                ) AS rn
+            FROM books b
+            JOIN ongoing_series os ON COALESCE(NULLIF(b.series, ''), 'unclassified') = os.name
+            LEFT JOIN book_reading_progress brp ON brp.book_id = b.id
+            WHERE COALESCE(brp.status, 'unread') != 'read'
+        )
+        SELECT id, library_id, kind, format, title, author, series, volume, language, page_count,
+               thumbnail_path, updated_at, reading_status, reading_current_page, reading_last_read_at
+        FROM next_books
+        WHERE rn = 1
+        ORDER BY series_last_read_at DESC NULLS LAST
+        LIMIT $1
+        "#,
+    )
+    .bind(limit)
+    .fetch_all(&state.pool)
+    .await?;
+
+    let items: Vec<BookItem> = rows
+        .iter()
+        .map(|row| {
+            let thumbnail_path: Option<String> = row.get("thumbnail_path");
+            BookItem {
+                id: row.get("id"),
+                library_id: row.get("library_id"),
+                kind: row.get("kind"),
+                format: row.get("format"),
+                title: row.get("title"),
+                author: row.get("author"),
+                series: row.get("series"),
+                volume: row.get("volume"),
+                language: row.get("language"),
+                page_count: row.get("page_count"),
+                thumbnail_url: thumbnail_path.map(|_| format!("/books/{}/thumbnail", row.get::<Uuid, _>("id"))),
+                updated_at: row.get("updated_at"),
+                reading_status: row.get("reading_status"),
+                reading_current_page: row.get("reading_current_page"),
+                reading_last_read_at: row.get("reading_last_read_at"),
+            }
+        })
+        .collect();
+
+    Ok(Json(items))
+}
+
+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,
 };
 
+/// Detect content type from thumbnail file extension.
+fn detect_thumbnail_content_type(path: &str) -> &'static str {
+    if path.ends_with(".jpg") || path.ends_with(".jpeg") {
+        "image/jpeg"
+    } else if path.ends_with(".png") {
+        "image/png"
+    } else {
+        "image/webp"
+    }
+}
+
+/// 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>,
@@ -360,16 +977,24 @@ pub async fn get_thumbnail(
     let row = row.ok_or_else(|| ApiError::not_found("book not found"))?;
     let thumbnail_path: Option<String> = row.get("thumbnail_path");
 
-    let data = if let Some(ref path) = thumbnail_path {
-        std::fs::read(path)
-            .map_err(|e| ApiError::internal(format!("cannot read thumbnail: {}", e)))?
+    let (data, content_type) = if let Some(ref path) = thumbnail_path {
+        match std::fs::read(path) {
+            Ok(bytes) => {
+                let ct = detect_thumbnail_content_type(path);
+                (bytes, ct)
+            }
+            Err(_) => {
+                // File missing on disk (e.g. different mount in dev) — fall back to live render
+                crate::pages::render_book_page_1(&state, book_id, 300, 80).await?
+            }
+        }
     } else {
-        // Fallback: render page 1 on the fly (same as pages logic)
+        // No stored thumbnail yet — render page 1 on the fly
         crate::pages::render_book_page_1(&state, book_id, 300, 80).await?
     };
 
     let mut headers = HeaderMap::new();
-    headers.insert(header::CONTENT_TYPE, HeaderValue::from_static("image/webp"));
+    headers.insert(header::CONTENT_TYPE, HeaderValue::from_static(content_type));
     headers.insert(
         header::CACHE_CONTROL,
         HeaderValue::from_static("public, max-age=31536000, immutable"),

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,18 @@ 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>>,
+    #[schema(value_type = Option<String>)]
+    pub generating_thumbnails_started_at: Option<DateTime<Utc>>,
     pub stats_json: Option<serde_json::Value>,
     pub error_opt: Option<String>,
     #[schema(value_type = String)]
@@ -122,7 +130,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 +153,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?;
@@ -174,7 +182,7 @@ pub async fn cancel_job(
     id: axum::extract::Path<Uuid>,
 ) -> Result<Json<IndexJobResponse>, ApiError> {
     let rows_affected = sqlx::query(
-        "UPDATE index_jobs SET status = 'cancelled' WHERE id = $1 AND status IN ('pending', 'running', 'generating_thumbnails')",
+        "UPDATE index_jobs SET status = 'cancelled' WHERE id = $1 AND status IN ('pending', 'running', 'extracting_pages', 'generating_thumbnails')",
     )
     .bind(id.0)
     .execute(&state.pool)
@@ -185,7 +193,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)
@@ -238,16 +246,16 @@ pub async fn list_folders(
         base_path.to_path_buf()
     };
     
-    // Ensure the path is within the libraries root
-    let canonical_target = target_path.canonicalize().unwrap_or(target_path.clone());
-    let canonical_base = base_path.canonicalize().unwrap_or(base_path.to_path_buf());
+    // Ensure the path is within the libraries root (avoid canonicalize — burns fd on Docker mounts)
+    let canonical_target = target_path.clone();
+    let canonical_base = base_path.to_path_buf();
     
     if !canonical_target.starts_with(&canonical_base) {
         return Err(ApiError::bad_request("Path is outside libraries root"));
     }
     
     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)
@@ -255,19 +263,31 @@ pub async fn list_folders(
         0
     };
 
-    if let Ok(entries) = std::fs::read_dir(&canonical_target) {
-        for entry in entries.flatten() {
-            if entry.file_type().map(|ft| ft.is_dir()).unwrap_or(false) {
+    let entries = std::fs::read_dir(&canonical_target)
+        .map_err(|e| ApiError::internal(format!("cannot read directory {}: {}", canonical_target.display(), e)))?;
+
+    for entry in entries {
+        let entry = match entry {
+            Ok(e) => e,
+            Err(e) => {
+                tracing::warn!("[FOLDERS] entry error in {}: {}", canonical_target.display(), e);
+                continue;
+            }
+        };
+        let is_dir = match entry.file_type() {
+            Ok(ft) => ft.is_dir(),
+            Err(e) => {
+                tracing::warn!("[FOLDERS] cannot stat {}: {}", entry.path().display(), e);
+                continue;
+            }
+        };
+        if is_dir {
                 let name = entry.file_name().to_string_lossy().to_string();
 
-                // Check if this folder has children
-                let has_children = if let Ok(sub_entries) = std::fs::read_dir(entry.path()) {
-                    sub_entries.flatten().any(|e| {
-                        e.file_type().map(|ft| ft.is_dir()).unwrap_or(false)
-                    })
-                } else {
-                    false
-                };
+                // Check if this folder has children (best-effort, default to true on error)
+                let has_children = std::fs::read_dir(entry.path())
+                    .map(|sub| sub.flatten().any(|e| e.file_type().map(|ft| ft.is_dir()).unwrap_or(false)))
+                    .unwrap_or(true);
                 
                 // Calculate the full path relative to libraries root
                 let full_path = if let Ok(relative) = entry.path().strip_prefix(&canonical_base) {
@@ -284,7 +304,6 @@ pub async fn list_folders(
                 });
         }
     }
-    }
 
     folders.sort_by(|a, b| a.name.cmp(&b.name));
     Ok(Json(folders))
@@ -294,6 +313,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 +331,13 @@ 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(),
+        generating_thumbnails_started_at: row.try_get("generating_thumbnails_started_at").ok().flatten(),
         stats_json: row.get("stats_json"),
         error_opt: row.get("error_opt"),
         created_at: row.get("created_at"),
@@ -339,9 +362,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
+        "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') 
+         WHERE status IN ('pending', 'running', 'extracting_pages', 'generating_thumbnails')
          ORDER BY created_at ASC"
     )
     .fetch_all(&state.pool)
@@ -371,8 +394,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, generating_thumbnails_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,
 }
@@ -155,14 +156,19 @@ fn canonicalize_library_root(root_path: &str) -> Result<PathBuf, ApiError> {
         return Err(ApiError::bad_request("root_path must be absolute"));
     }
 
-    let canonical = std::fs::canonicalize(path)
-        .map_err(|_| ApiError::bad_request("root_path does not exist or is inaccessible"))?;
-
-    if !canonical.is_dir() {
+    // Avoid fs::canonicalize — it opens extra file descriptors to resolve symlinks
+    // and can fail on Docker volume mounts (ro, cached) when fd limits are low.
+    if !path.exists() {
+        return Err(ApiError::bad_request(format!(
+            "root_path does not exist: {}",
+            root_path
+        )));
+    }
+    if !path.is_dir() {
         return Err(ApiError::bad_request("root_path must point to a directory"));
     }
 
-    Ok(canonical)
+    Ok(path.to_path_buf())
 }
 
 use crate::index_jobs::{IndexJobResponse, RebuildRequest};

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,12 +91,12 @@ 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))
         .route("/admin/tokens", get(tokens::list_tokens).post(tokens::create_token))
         .route("/admin/tokens/:id", delete(tokens::revoke_token))
+        .route("/admin/tokens/:id/delete", axum::routing::post(tokens::delete_token))
         .merge(settings::settings_routes())
         .route_layer(middleware::from_fn_with_state(
             state.clone(),
@@ -120,26 +105,31 @@ async fn main() -> anyhow::Result<()> {
 
     let read_routes = Router::new()
         .route("/books", get(books::list_books))
+        .route("/books/ongoing", get(books::ongoing_books))
         .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("/series", get(books::list_all_series))
+        .route("/series/ongoing", get(books::ongoing_series))
+        .route("/series/mark-read", axum::routing::post(reading_progress::mark_series_read))
         .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 +138,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,15 @@ 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::reading_progress::mark_series_read,
+        crate::books::get_thumbnail,
         crate::books::list_series,
+        crate::books::list_all_series,
+        crate::books::ongoing_series,
+        crate::books::ongoing_books,
+        crate::books::convert_book,
         crate::pages::get_page,
         crate::search::search_books,
         crate::index_jobs::enqueue_rebuild,
@@ -27,6 +35,13 @@ use utoipa::OpenApi;
         crate::tokens::list_tokens,
         crate::tokens::create_token,
         crate::tokens::revoke_token,
+        crate::tokens::delete_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,10 +49,18 @@ use utoipa::OpenApi;
             crate::books::BookItem,
             crate::books::BooksPage,
             crate::books::BookDetails,
+            crate::reading_progress::ReadingProgressResponse,
+            crate::reading_progress::UpdateReadingProgressRequest,
+            crate::reading_progress::MarkSeriesReadRequest,
+            crate::reading_progress::MarkSeriesReadResponse,
             crate::books::SeriesItem,
+            crate::books::SeriesPage,
+            crate::books::ListAllSeriesQuery,
+            crate::books::OngoingQuery,
             crate::pages::PageQuery,
             crate::search::SearchQuery,
             crate::search::SearchResponse,
+            crate::search::SeriesHit,
             crate::index_jobs::RebuildRequest,
             crate::thumbnails::ThumbnailsRebuildRequest,
             crate::index_jobs::IndexJobResponse,
@@ -51,6 +74,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 +86,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 +135,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

@@ -1,5 +1,5 @@
 use std::{
-    io::{Read, Write},
+    io::Write,
     path::{Path, PathBuf},
     sync::{atomic::Ordering, Arc},
     time::Duration,
@@ -16,11 +16,10 @@ use serde::Deserialize;
 use utoipa::ToSchema;
 use sha2::{Digest, Sha256};
 use sqlx::Row;
-use tracing::{debug, error, info, instrument, warn};
+use tracing::{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 +30,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 {
+        "lanczos3" => image::imageops::FilterType::Lanczos3,
+        "nearest" => image::imageops::FilterType::Nearest,
+        _ => image::imageops::FilterType::Triangle, // Triangle (bilinear) is fast and good enough for comics
+    }
 }
 
 fn get_cache_key(abs_path: &str, page: u32, format: &str, quality: u8, width: u32) -> String {
@@ -47,8 +48,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))
@@ -64,7 +64,7 @@ fn write_to_disk_cache(cache_path: &Path, data: &[u8]) -> Result<(), std::io::Er
     }
     let mut file = std::fs::File::create(cache_path)?;
     file.write_all(data)?;
-    file.sync_data()?;
+    // No sync_data() — this is a cache, durability is not critical
     Ok(())
 }
 
@@ -80,6 +80,8 @@ pub struct PageQuery {
 
 #[derive(Clone, Copy, Debug)]
 enum OutputFormat {
+    /// Serve raw bytes from the archive — no decode, no re-encode.
+    Original,
     Jpeg,
     Png,
     Webp,
@@ -87,16 +89,19 @@ enum OutputFormat {
 
 impl OutputFormat {
     fn parse(value: Option<&str>) -> Result<Self, ApiError> {
-        match value.unwrap_or("webp") {
-            "jpeg" | "jpg" => Ok(Self::Jpeg),
-            "png" => Ok(Self::Png),
-            "webp" => Ok(Self::Webp),
-            _ => Err(ApiError::bad_request("format must be webp|jpeg|png")),
+        match value {
+            None => Ok(Self::Original),
+            Some("original") => Ok(Self::Original),
+            Some("jpeg") | Some("jpg") => Ok(Self::Jpeg),
+            Some("png") => Ok(Self::Png),
+            Some("webp") => Ok(Self::Webp),
+            _ => Err(ApiError::bad_request("format must be original|webp|jpeg|png")),
         }
     }
 
     fn content_type(&self) -> &'static str {
         match self {
+            Self::Original => "application/octet-stream", // will be overridden by detected type
             Self::Jpeg => "image/jpeg",
             Self::Png => "image/png",
             Self::Webp => "image/webp",
@@ -105,6 +110,7 @@ impl OutputFormat {
 
     fn extension(&self) -> &'static str {
         match self {
+            Self::Original => "orig",
             Self::Jpeg => "jpg",
             Self::Png => "png",
             Self::Webp => "webp",
@@ -112,6 +118,17 @@ impl OutputFormat {
     }
 }
 
+/// Detect content type from raw image bytes.
+fn detect_content_type(data: &[u8]) -> &'static str {
+    match image::guess_format(data) {
+        Ok(ImageFormat::Jpeg) => "image/jpeg",
+        Ok(ImageFormat::Png) => "image/png",
+        Ok(ImageFormat::WebP) => "image/webp",
+        Ok(ImageFormat::Avif) => "image/avif",
+        _ => "application/octet-stream",
+    }
+}
+
 /// Get a specific page image from a book with optional format conversion
 #[utoipa::path(
     get,
@@ -132,36 +149,38 @@ impl OutputFormat {
     ),
     security(("Bearer" = []))
 )]
-#[instrument(skip(state), fields(book_id = %book_id, page = n))]
+#[instrument(skip(state, headers), fields(book_id = %book_id, page = n))]
 pub async fn get_page(
     State(state): State<AppState>,
     AxumPath((book_id, n)): AxumPath<(Uuid, u32)>,
     Query(query): Query<PageQuery>,
+    headers: HeaderMap,
 ) -> Result<Response, ApiError> {
-    info!("Processing image request");
-    
     if n == 0 {
-        warn!("Invalid page number: 0");
         return Err(ApiError::bad_request("page index starts at 1"));
     }
 
+    let (default_quality, max_width, filter_str, timeout_secs, cache_dir) = {
+        let s = state.settings.read().await;
+        (s.image_quality, s.image_max_width, s.image_filter.clone(), s.timeout_seconds, s.cache_directory.clone())
+    };
+
     let format = OutputFormat::parse(query.format.as_deref())?;
-    let quality = query.quality.unwrap_or(80).clamp(1, 100);
+    let quality = query.quality.unwrap_or(default_quality).clamp(1, 100);
     let width = query.width.unwrap_or(0);
-    if width > 2160 {
-        warn!("Invalid width: {}", width);
-        return Err(ApiError::bad_request("width must be <= 2160"));
+    if width > max_width {
+        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());
 
     if let Some(cached) = state.page_cache.lock().await.get(&memory_cache_key).cloned() {
         state.metrics.page_cache_hits.fetch_add(1, Ordering::Relaxed);
-        debug!("Memory cache hit for key: {}", memory_cache_key);
-        return Ok(image_response(cached, format.content_type(), None));
+        return Ok(image_response(cached, format, None, &headers));
     }
     state.metrics.page_cache_misses.fetch_add(1, Ordering::Relaxed);
-    debug!("Memory cache miss for key: {}", memory_cache_key);
 
     let row = sqlx::query(
         r#"
@@ -183,7 +202,6 @@ pub async fn get_page(
     let row = match row {
         Some(r) => r,
         None => {
-            error!("Book file not found for book_id: {}", book_id);
             return Err(ApiError::not_found("book file not found"));
         }
     };
@@ -192,18 +210,22 @@ pub async fn get_page(
     let abs_path = remap_libraries_path(&abs_path);
     let input_format: String = row.get("format");
 
-    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-None-Match: return 304 if the client already has this version
+    if let Some(if_none_match) = headers.get(header::IF_NONE_MATCH) {
+        let expected_etag = format!("\"{}\"", disk_cache_key);
+        if if_none_match.as_bytes() == expected_etag.as_bytes() {
+            return Ok(StatusCode::NOT_MODIFIED.into_response());
+        }
+    }
 
     if let Some(cached_bytes) = read_from_disk_cache(&cache_path) {
-        info!("Disk cache hit for: {}", cache_path.display());
         let bytes = Arc::new(cached_bytes);
         state.page_cache.lock().await.put(memory_cache_key, bytes.clone());
-        return Ok(image_response(bytes, format.content_type(), Some(&disk_cache_key)));
+        return Ok(image_response(bytes, format, Some(&disk_cache_key), &headers));
     }
-    debug!("Disk cache miss for: {}", cache_path.display());
 
     let _permit = state
         .page_render_limit
@@ -215,15 +237,14 @@ pub async fn get_page(
             ApiError::internal("render limiter unavailable")
         })?;
 
-    info!("Rendering page {} from {}", n, abs_path);
     let abs_path_clone = abs_path.clone();
     let format_clone = format;
     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
@@ -240,18 +261,27 @@ pub async fn get_page(
 
     match bytes {
         Ok(data) => {
-            info!("Successfully rendered page {} in {:?}", n, duration);
+            info!("Rendered page {} in {:?}", n, duration);
 
             if let Err(e) = write_to_disk_cache(&cache_path, &data) {
                 warn!("Failed to write to disk cache: {}", e);
-            } else {
-                info!("Cached rendered image to: {}", cache_path.display());
             }
 
             let bytes = Arc::new(data);
-            state.page_cache.lock().await.put(memory_cache_key, bytes.clone());
+            state.page_cache.lock().await.put(memory_cache_key.clone(), bytes.clone());
 
-            Ok(image_response(bytes, format.content_type(), Some(&disk_cache_key)))
+            // Prefetch next 2 pages in background (fire-and-forget)
+            for next_page in [n + 1, n + 2] {
+                let state2 = state.clone();
+                let abs_path2 = abs_path.clone();
+                let cache_dir2 = cache_dir_path.clone();
+                let format2 = format;
+                tokio::spawn(async move {
+                    prefetch_page(state2, book_id, &abs_path2, next_page, format2, quality, width, filter, timeout_secs, &cache_dir2).await;
+                });
+            }
+
+            Ok(image_response(bytes, format, Some(&disk_cache_key), &headers))
         }
         Err(e) => {
             error!("Failed to render page {} from {}: {:?}", n, abs_path, e);
@@ -260,11 +290,72 @@ pub async fn get_page(
     }
 }
 
-fn image_response(bytes: Arc<Vec<u8>>, content_type: &str, etag_suffix: Option<&str>) -> Response {
-    let mut headers = HeaderMap::new();
-    headers.insert(header::CONTENT_TYPE, HeaderValue::from_str(content_type).unwrap_or(HeaderValue::from_static("application/octet-stream")));
-    headers.insert(header::CACHE_CONTROL, HeaderValue::from_static("public, max-age=31536000, immutable"));
+/// Prefetch a single page into disk+memory cache (best-effort, ignores errors).
+async fn prefetch_page(
+    state: AppState,
+    book_id: Uuid,
+    abs_path: &str,
+    page: u32,
+    format: OutputFormat,
+    quality: u8,
+    width: u32,
+    filter: image::imageops::FilterType,
+    timeout_secs: u64,
+    cache_dir: &Path,
+) {
+    let mem_key = format!("{book_id}:{page}:{}:{quality}:{width}", format.extension());
+    // Already in memory cache?
+    if state.page_cache.lock().await.contains(&mem_key) {
+        return;
+    }
+    // Already on disk?
+    let disk_key = get_cache_key(abs_path, page, format.extension(), quality, width);
+    let cache_path = get_cache_path(&disk_key, &format, cache_dir);
+    if cache_path.exists() {
+        return;
+    }
+    // Acquire render permit (don't block too long — if busy, skip)
+    let permit = tokio::time::timeout(
+        Duration::from_millis(100),
+        state.page_render_limit.clone().acquire_owned(),
+    )
+    .await;
+    let _permit = match permit {
+        Ok(Ok(p)) => p,
+        _ => return,
+    };
 
+    // Fetch the book format from the path extension as a shortcut
+    let input_format = match abs_path.rsplit('.').next().map(|e| e.to_ascii_lowercase()) {
+        Some(ref e) if e == "cbz" => "cbz",
+        Some(ref e) if e == "cbr" => "cbr",
+        Some(ref e) if e == "pdf" => "pdf",
+        _ => return,
+    }
+    .to_string();
+
+    let abs_clone = abs_path.to_string();
+    let fmt = format;
+    let result = tokio::time::timeout(
+        Duration::from_secs(timeout_secs),
+        tokio::task::spawn_blocking(move || {
+            render_page(&abs_clone, &input_format, page, &fmt, quality, width, filter)
+        }),
+    )
+    .await;
+
+    if let Ok(Ok(Ok(data))) = result {
+        let _ = write_to_disk_cache(&cache_path, &data);
+        let bytes = Arc::new(data);
+        state.page_cache.lock().await.put(mem_key, bytes);
+    }
+}
+
+fn image_response(bytes: Arc<Vec<u8>>, format: OutputFormat, etag_suffix: Option<&str>, req_headers: &HeaderMap) -> Response {
+    let content_type = match format {
+        OutputFormat::Original => detect_content_type(&bytes),
+        _ => format.content_type(),
+    };
     let etag = if let Some(suffix) = etag_suffix {
         format!("\"{}\"", suffix)
     } else {
@@ -273,19 +364,37 @@ fn image_response(bytes: Arc<Vec<u8>>, content_type: &str, etag_suffix: Option<&
         format!("\"{:x}\"", hasher.finalize())
     };
 
+    // Check If-None-Match for 304
+    if let Some(if_none_match) = req_headers.get(header::IF_NONE_MATCH) {
+        if if_none_match.as_bytes() == etag.as_bytes() {
+            let mut headers = HeaderMap::new();
+            headers.insert(header::CACHE_CONTROL, HeaderValue::from_static("public, max-age=31536000, immutable"));
             if let Ok(v) = HeaderValue::from_str(&etag) {
                 headers.insert(header::ETAG, v);
             }
-    (StatusCode::OK, headers, Body::from((*bytes).clone())).into_response()
+            return (StatusCode::NOT_MODIFIED, headers).into_response();
+        }
+    }
+
+    let mut headers = HeaderMap::new();
+    headers.insert(header::CONTENT_TYPE, HeaderValue::from_str(content_type).unwrap_or(HeaderValue::from_static("application/octet-stream")));
+    headers.insert(header::CACHE_CONTROL, HeaderValue::from_static("public, max-age=31536000, immutable"));
+    if let Ok(v) = HeaderValue::from_str(&etag) {
+        headers.insert(header::ETAG, v);
+    }
+    // Use Bytes to avoid cloning the Vec — shares the Arc's allocation via zero-copy
+    let body_bytes = axum::body::Bytes::from(Arc::unwrap_or_clone(bytes));
+    (StatusCode::OK, headers, Body::from(body_bytes)).into_response()
 }
 
 /// Render page 1 of a book (for thumbnail fallback or thumbnail checkup). Uses thumbnail dimensions by default.
+/// Render page 1 as a thumbnail fallback. Returns (bytes, content_type).
 pub async fn render_book_page_1(
     state: &AppState,
     book_id: Uuid,
     width: u32,
     quality: u8,
-) -> Result<Vec<u8>, ApiError> {
+) -> Result<(Vec<u8>, &'static str), ApiError> {
     let row = sqlx::query(
         r#"SELECT abs_path, format FROM book_files WHERE book_id = $1 ORDER BY updated_at DESC LIMIT 1"#,
     )
@@ -306,17 +415,24 @@ 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,
                 &input_format,
                 1,
-                &OutputFormat::Webp,
+                &OutputFormat::Original,
                 quality,
                 width,
+                filter,
             )
         }),
     )
@@ -324,7 +440,9 @@ pub async fn render_book_page_1(
     .map_err(|_| ApiError::internal("page rendering timeout"))?
     .map_err(|e| ApiError::internal(format!("render task failed: {e}")))?;
 
-    bytes
+    let bytes = bytes?;
+    let content_type = detect_content_type(&bytes);
+    Ok((bytes, content_type))
 }
 
 fn render_page(
@@ -334,200 +452,114 @@ 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)?,
-        "cbr" => extract_cbr_page(abs_path, page_number)?,
-        "pdf" => render_pdf_page(abs_path, page_number, width)?,
+    let format = match input_format {
+        "cbz" => parsers::BookFormat::Cbz,
+        "cbr" => parsers::BookFormat::Cbr,
+        "pdf" => parsers::BookFormat::Pdf,
         _ => return Err(ApiError::bad_request("unsupported source format")),
     };
 
-    transcode_image(&page_bytes, out_format, quality, width)
-}
-
-fn extract_cbz_page(abs_path: &str, page_number: u32) -> Result<Vec<u8>, ApiError> {
-    debug!("Opening CBZ archive: {}", abs_path);
-    let file = std::fs::File::open(abs_path).map_err(|e| {
-        error!("Cannot open CBZ file {}: {}", abs_path, e);
-        ApiError::internal(format!("cannot open cbz: {e}"))
-    })?;
-    
-    let mut archive = zip::ZipArchive::new(file).map_err(|e| {
-        error!("Invalid CBZ archive {}: {}", abs_path, e);
-        ApiError::internal(format!("invalid cbz: {e}"))
-    })?;
-
-    let mut image_names: Vec<String> = Vec::new();
-    for i in 0..archive.len() {
-        let entry = archive.by_index(i).map_err(|e| {
-            error!("Failed to read CBZ entry {} in {}: {}", i, abs_path, e);
-            ApiError::internal(format!("cbz entry read failed: {e}"))
-        })?;
-        let name = entry.name().to_ascii_lowercase();
-        if is_image_name(&name) {
-            image_names.push(entry.name().to_string());
-        }
-    }
-    image_names.sort();
-    debug!("Found {} images in CBZ {}", image_names.len(), abs_path);
-
-    let index = page_number as usize - 1;
-    let selected = image_names.get(index).ok_or_else(|| {
-        error!("Page {} out of range in {} (total: {})", page_number, abs_path, image_names.len());
-        ApiError::not_found("page out of range")
-    })?;
-    
-    debug!("Extracting page {} ({}) from {}", page_number, selected, abs_path);
-    let mut entry = archive.by_name(selected).map_err(|e| {
-        error!("Failed to read CBZ page {} from {}: {}", selected, abs_path, e);
-        ApiError::internal(format!("cbz page read failed: {e}"))
-    })?;
-    let mut buf = Vec::new();
-    entry.read_to_end(&mut buf).map_err(|e| {
-        error!("Failed to load CBZ page {} from {}: {}", selected, abs_path, e);
-        ApiError::internal(format!("cbz page load failed: {e}"))
-    })?;
-    Ok(buf)
-}
-
-fn extract_cbr_page(abs_path: &str, page_number: u32) -> Result<Vec<u8>, ApiError> {
-    info!("Opening CBR archive: {}", abs_path);
-    
-    let index = page_number as usize - 1;
-    let tmp_dir = std::env::temp_dir().join(format!("stripstream-cbr-{}", Uuid::new_v4()));
-    debug!("Creating temp dir for CBR extraction: {}", tmp_dir.display());
-    
-    std::fs::create_dir_all(&tmp_dir).map_err(|e| {
-        error!("Cannot create temp dir: {}", e);
-        ApiError::internal(format!("temp dir error: {}", e))
-    })?;
-
-    // Extract directly - skip listing which fails on UTF-16 encoded filenames
-    let extract_output = std::process::Command::new("env")
-        .args(["LC_ALL=en_US.UTF-8", "LANG=en_US.UTF-8", "unar", "-o"])
-        .arg(&tmp_dir)
-        .arg(abs_path)
-        .output()
+    let pdf_render_width = if width > 0 { width } else { 1200 };
+    let page_bytes = parsers::extract_page(
+        std::path::Path::new(abs_path),
+        format,
+        page_number,
+        pdf_render_width,
+    )
     .map_err(|e| {
-            let _ = std::fs::remove_dir_all(&tmp_dir);
-            error!("unar extract failed: {}", e);
-            ApiError::internal(format!("unar extract failed: {e}"))
+        error!("Failed to extract page {} from {}: {}", page_number, abs_path, e);
+        ApiError::internal(format!("page extraction failed: {e}"))
     })?;
 
-    if !extract_output.status.success() {
-        let _ = std::fs::remove_dir_all(&tmp_dir);
-        let stderr = String::from_utf8_lossy(&extract_output.stderr);
-        error!("unar extract failed {}: {}", abs_path, stderr);
-        return Err(ApiError::internal("unar extract failed"));
+    // Original mode or source matches output with no resize → return raw bytes (zero transcoding)
+    if matches!(out_format, OutputFormat::Original) && width == 0 {
+        return Ok(page_bytes);
+    }
+    if width == 0 {
+        if let Ok(source_fmt) = image::guess_format(&page_bytes) {
+            if format_matches(&source_fmt, out_format) {
+                return Ok(page_bytes);
+            }
+        }
     }
 
-    // Find and read the requested image (recursive search for CBR files with subdirectories)
-    let mut image_files: Vec<_> = WalkDir::new(&tmp_dir)
-        .into_iter()
-        .filter_map(|e| e.ok())
-        .filter(|e| {
-            let name = e.file_name().to_string_lossy().to_lowercase();
-            is_image_name(&name)
-        })
-        .collect();
-    
-    image_files.sort_by_key(|e| e.path().to_string_lossy().to_lowercase());
-
-    let selected = image_files.get(index).ok_or_else(|| {
-        let _ = std::fs::remove_dir_all(&tmp_dir);
-        error!("Page {} not found (total: {})", page_number, image_files.len());
-        ApiError::not_found("page out of range")
-    })?;
-
-    let data = std::fs::read(selected.path()).map_err(|e| {
-        let _ = std::fs::remove_dir_all(&tmp_dir);
-        error!("read failed: {}", e);
-        ApiError::internal(format!("read error: {}", e))
-    })?;
-
-    let _ = std::fs::remove_dir_all(&tmp_dir);
-    
-    info!("Successfully extracted CBR page {} ({} bytes)", page_number, data.len());
-    Ok(data)
+    transcode_image(&page_bytes, out_format, quality, width, filter)
 }
 
-fn render_pdf_page(abs_path: &str, page_number: u32, width: u32) -> Result<Vec<u8>, ApiError> {
-    let tmp_dir = std::env::temp_dir().join(format!("stripstream-pdf-{}", Uuid::new_v4()));
-    debug!("Creating temp dir for PDF rendering: {}", tmp_dir.display());
-    std::fs::create_dir_all(&tmp_dir).map_err(|e| {
-        error!("Cannot create temp dir {}: {}", tmp_dir.display(), e);
-        ApiError::internal(format!("cannot create temp dir: {e}"))
-    })?;
-    let output_prefix = tmp_dir.join("page");
 
-    let mut cmd = std::process::Command::new("pdftoppm");
-    cmd.arg("-f")
-        .arg(page_number.to_string())
-        .arg("-singlefile")
-        .arg("-png");
-    if width > 0 {
-        cmd.arg("-scale-to-x").arg(width.to_string()).arg("-scale-to-y").arg("-1");
+/// Fast JPEG decode with DCT scaling: decodes directly at reduced resolution.
+fn fast_jpeg_decode(input: &[u8], target_w: u32, target_h: u32) -> Option<image::DynamicImage> {
+    if image::guess_format(input).ok()? != ImageFormat::Jpeg {
+        return None;
+    }
+    let mut decoder = jpeg_decoder::Decoder::new(std::io::Cursor::new(input));
+    decoder.read_info().ok()?;
+    decoder.scale(target_w as u16, target_h as u16).ok()?;
+    let pixels = decoder.decode().ok()?;
+    let info = decoder.info()?;
+    let w = info.width as u32;
+    let h = info.height as u32;
+    match info.pixel_format {
+        jpeg_decoder::PixelFormat::RGB24 => {
+            let buf = image::RgbImage::from_raw(w, h, pixels)?;
+            Some(image::DynamicImage::ImageRgb8(buf))
+        }
+        jpeg_decoder::PixelFormat::L8 => {
+            let buf = image::GrayImage::from_raw(w, h, pixels)?;
+            Some(image::DynamicImage::ImageLuma8(buf))
+        }
+        _ => None,
     }
-    cmd.arg(abs_path).arg(&output_prefix);
-
-    debug!("Running pdftoppm for page {} of {} (width: {})", page_number, abs_path, width);
-    let output = cmd
-        .output()
-        .map_err(|e| {
-            error!("pdftoppm command failed for {} page {}: {}", abs_path, page_number, e);
-            ApiError::internal(format!("pdf render failed: {e}"))
-        })?;
-    if !output.status.success() {
-        let stderr = String::from_utf8_lossy(&output.stderr);
-        let _ = std::fs::remove_dir_all(&tmp_dir);
-        error!("pdftoppm failed for {} page {}: {}", abs_path, page_number, stderr);
-        return Err(ApiError::internal("pdf render command failed"));
 }
 
-    let image_path = output_prefix.with_extension("png");
-    debug!("Reading rendered PDF page from: {}", image_path.display());
-    let bytes = std::fs::read(&image_path).map_err(|e| {
-        error!("Failed to read rendered PDF output {}: {}", image_path.display(), e);
-        ApiError::internal(format!("render output missing: {e}"))
-    })?;
-    let _ = std::fs::remove_dir_all(&tmp_dir);
-    debug!("Successfully rendered PDF page {} to {} bytes", page_number, bytes.len());
-    Ok(bytes)
-}
-
-fn transcode_image(input: &[u8], out_format: &OutputFormat, quality: u8, width: u32) -> Result<Vec<u8>, ApiError> {
-    debug!("Transcoding image: {} bytes, format: {:?}, quality: {}, width: {}", input.len(), out_format, quality, width);
+fn transcode_image(input: &[u8], out_format: &OutputFormat, quality: u8, width: u32, filter: image::imageops::FilterType) -> Result<Vec<u8>, ApiError> {
     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);
+
+    // Resolve "Original" to the actual source format for encoding
+    let effective_format = match out_format {
+        OutputFormat::Original => match source_format {
+            Some(ImageFormat::Png) => OutputFormat::Png,
+            Some(ImageFormat::WebP) => OutputFormat::Webp,
+            _ => OutputFormat::Jpeg, // default to JPEG for original resize
+        },
+        other => *other,
+    };
+
+    let needs_transcode = source_format.map(|f| !format_matches(&f, &effective_format)).unwrap_or(true);
 
     if width == 0 && !needs_transcode {
-        debug!("No transcoding needed, returning original");
         return Ok(input.to_vec());
     }
 
-    debug!("Loading image from memory...");
-    let mut image = image::load_from_memory(input).map_err(|e| {
-        error!("Failed to load image from memory: {} (input size: {} bytes)", e, input.len());
+    // For JPEG with resize: use DCT scaling to decode at ~target size (much faster)
+    let mut image = if width > 0 {
+        fast_jpeg_decode(input, width, u32::MAX)
+            .unwrap_or_else(|| {
+                image::load_from_memory(input).unwrap_or_default()
+            })
+    } else {
+        image::load_from_memory(input).map_err(|e| {
             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...");
     let rgba = image.to_rgba8();
     let (w, h) = rgba.dimensions();
-    debug!("Image dimensions: {}x{}", w, h);
 
     let mut out = Vec::new();
-    match out_format {
-        OutputFormat::Jpeg => {
+    match effective_format {
+        OutputFormat::Jpeg | OutputFormat::Original => {
+            // JPEG doesn't support alpha — convert RGBA to RGB
+            let rgb = image::DynamicImage::ImageRgba8(rgba.clone()).to_rgb8();
             let mut encoder = JpegEncoder::new_with_quality(&mut out, quality);
             encoder
-                .encode(&rgba, w, h, ColorType::Rgba8.into())
+                .encode(&rgb, w, h, ColorType::Rgb8.into())
                 .map_err(|e| ApiError::internal(format!("jpeg encode failed: {e}")))?;
         }
         OutputFormat::Png => {
@@ -542,7 +574,7 @@ fn transcode_image(input: &[u8], out_format: &OutputFormat, quality: u8, width:
                 .flat_map(|p| [p[0], p[1], p[2]])
                 .collect();
             let webp_data = webp::Encoder::new(&rgb_data, webp::PixelLayout::Rgb, w, h)
-                .encode(f32::max(quality as f32, 85.0));
+                .encode(quality as f32);
             out.extend_from_slice(&webp_data);
         }
     }
@@ -550,28 +582,11 @@ 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 {
-    let lower = name.to_lowercase();
-    lower.ends_with(".jpg")
-        || lower.ends_with(".jpeg")
-        || lower.ends_with(".png")
-        || lower.ends_with(".webp")
-        || lower.ends_with(".avif")
-        || lower.ends_with(".gif")
-        || lower.ends_with(".tif")
-        || lower.ends_with(".tiff")
-        || lower.ends_with(".bmp")
-}
-
-#[allow(dead_code)]
-fn _is_absolute_path(value: &str) -> bool {
-    Path::new(value).is_absolute()
-}

apps/api/src/reading_progress.rs

@@ -0,0 +1,247 @@
+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"),
+    }))
+}
+
+#[derive(Deserialize, ToSchema)]
+pub struct MarkSeriesReadRequest {
+    /// Series name (use "unclassified" for books without series)
+    pub series: String,
+    /// Status to set: "read" or "unread"
+    pub status: String,
+}
+
+#[derive(Serialize, ToSchema)]
+pub struct MarkSeriesReadResponse {
+    pub updated: i64,
+}
+
+/// Mark all books in a series as read or unread
+#[utoipa::path(
+    post,
+    path = "/series/mark-read",
+    tag = "reading-progress",
+    request_body = MarkSeriesReadRequest,
+    responses(
+        (status = 200, body = MarkSeriesReadResponse),
+        (status = 422, description = "Invalid status"),
+        (status = 401, description = "Unauthorized"),
+    ),
+    security(("Bearer" = []))
+)]
+pub async fn mark_series_read(
+    State(state): State<AppState>,
+    Json(body): Json<MarkSeriesReadRequest>,
+) -> Result<Json<MarkSeriesReadResponse>, ApiError> {
+    if !["read", "unread"].contains(&body.status.as_str()) {
+        return Err(ApiError::bad_request(
+            "status must be 'read' or 'unread'",
+        ));
+    }
+
+    let series_filter = if body.series == "unclassified" {
+        "(series IS NULL OR series = '')"
+    } else {
+        "series = $1"
+    };
+
+    let sql = if body.status == "unread" {
+        // Delete progress records to reset to unread
+        format!(
+            r#"
+            WITH target_books AS (
+                SELECT id FROM books WHERE {series_filter}
+            )
+            DELETE FROM book_reading_progress
+            WHERE book_id IN (SELECT id FROM target_books)
+            "#
+        )
+    } else {
+        format!(
+            r#"
+            INSERT INTO book_reading_progress (book_id, status, current_page, last_read_at, updated_at)
+            SELECT id, 'read', NULL, NOW(), NOW()
+            FROM books
+            WHERE {series_filter}
+            ON CONFLICT (book_id) DO UPDATE
+              SET status = 'read',
+                  current_page = NULL,
+                  last_read_at = NOW(),
+                  updated_at = NOW()
+            "#
+        )
+    };
+
+    let result = if body.series == "unclassified" {
+        sqlx::query(&sql).execute(&state.pool).await?
+    } else {
+        sqlx::query(&sql).bind(&body.series).execute(&state.pool).await?
+    };
+
+    Ok(Json(MarkSeriesReadResponse {
+        updated: result.rows_affected() as i64,
+    }))
+}

apps/api/src/search.rs

@@ -1,8 +1,10 @@
 use axum::{extract::{Query, State}, Json};
 use serde::{Deserialize, Serialize};
+use sqlx::Row;
 use utoipa::ToSchema;
+use uuid::Uuid;
 
-use crate::{error::ApiError, AppState};
+use crate::{error::ApiError, state::AppState};
 
 #[derive(Deserialize, ToSchema)]
 pub struct SearchQuery {
@@ -18,9 +20,21 @@ pub struct SearchQuery {
     pub limit: Option<usize>,
 }
 
+#[derive(Serialize, ToSchema)]
+pub struct SeriesHit {
+    #[schema(value_type = String)]
+    pub library_id: Uuid,
+    pub name: String,
+    pub book_count: i64,
+    pub books_read_count: i64,
+    #[schema(value_type = String)]
+    pub first_book_id: Uuid,
+}
+
 #[derive(Serialize, ToSchema)]
 pub struct SearchResponse {
     pub hits: serde_json::Value,
+    pub series_hits: Vec<SeriesHit>,
     pub estimated_total_hits: Option<u64>,
     pub processing_time_ms: Option<u64>,
 }
@@ -31,11 +45,11 @@ pub struct SearchResponse {
     path = "/search",
     tag = "books",
     params(
-        ("q" = String, Query, description = "Search query"),
+        ("q" = String, Query, description = "Search query (books via Meilisearch + series via ILIKE)"),
         ("library_id" = Option<String>, Query, description = "Filter by library ID"),
         ("type" = Option<String>, Query, description = "Filter by type (cbz, cbr, pdf)"),
         ("kind" = Option<String>, Query, description = "Filter by kind (alias for type)"),
-        ("limit" = Option<usize>, Query, description = "Max results (max 100)"),
+        ("limit" = Option<usize>, Query, description = "Max results per type (max 100)"),
     ),
     responses(
         (status = 200, body = SearchResponse),
@@ -66,36 +80,98 @@ pub async fn search_books(
         "filter": if filters.is_empty() { serde_json::Value::Null } else { serde_json::Value::String(filters.join(" AND ")) }
     });
 
+    let limit_val = query.limit.unwrap_or(20).clamp(1, 100);
+    let q_pattern = format!("%{}%", query.q);
+    let library_id_uuid: Option<uuid::Uuid> = query.library_id.as_deref()
+        .and_then(|s| s.parse().ok());
+
+    // Recherche Meilisearch (books) + séries PG en parallèle
     let client = reqwest::Client::new();
     let url = format!("{}/indexes/books/search", state.meili_url.trim_end_matches('/'));
-    let response = client
-        .post(url)
+    let meili_fut = client
+        .post(&url)
         .header("Authorization", format!("Bearer {}", state.meili_master_key))
         .json(&body)
-        .send()
-        .await
-        .map_err(|e| ApiError::internal(format!("meili request failed: {e}")))?;
+        .send();
 
-    if !response.status().is_success() {
-        let body = response.text().await.unwrap_or_else(|_| "unknown meili error".to_string());
+    let series_sql = r#"
+        WITH sorted_books AS (
+            SELECT
+                library_id,
+                COALESCE(NULLIF(series, ''), 'unclassified') as name,
+                id,
+                ROW_NUMBER() OVER (
+                    PARTITION BY library_id, COALESCE(NULLIF(series, ''), 'unclassified')
+                    ORDER BY
+                        REGEXP_REPLACE(LOWER(title), '[0-9]+', '', 'g'),
+                        COALESCE((REGEXP_MATCH(LOWER(title), '\d+'))[1]::int, 0),
+                        title ASC
+                ) as rn
+            FROM books
+            WHERE ($1::uuid IS NULL OR library_id = $1)
+        ),
+        series_counts AS (
+            SELECT
+                sb.library_id,
+                sb.name,
+                COUNT(*) as book_count,
+                COUNT(brp.book_id) FILTER (WHERE brp.status = 'read') as books_read_count
+            FROM sorted_books sb
+            LEFT JOIN book_reading_progress brp ON brp.book_id = sb.id
+            GROUP BY sb.library_id, sb.name
+        )
+        SELECT sc.library_id, sc.name, sc.book_count, sc.books_read_count, sb.id as first_book_id
+        FROM series_counts sc
+        JOIN sorted_books sb ON sb.library_id = sc.library_id AND sb.name = sc.name AND sb.rn = 1
+        WHERE sc.name ILIKE $2
+        ORDER BY sc.name ASC
+        LIMIT $3
+    "#;
+
+    let series_fut = sqlx::query(series_sql)
+        .bind(library_id_uuid)
+        .bind(&q_pattern)
+        .bind(limit_val as i64)
+        .fetch_all(&state.pool);
+
+    let (meili_resp, series_rows) = tokio::join!(meili_fut, series_fut);
+
+    // Traitement Meilisearch
+    let meili_resp = meili_resp.map_err(|e| ApiError::internal(format!("meili request failed: {e}")))?;
+    let (hits, estimated_total_hits, processing_time_ms) = if !meili_resp.status().is_success() {
+        let body = meili_resp.text().await.unwrap_or_default();
         if body.contains("index_not_found") {
-            return Ok(Json(SearchResponse {
-                hits: serde_json::json!([]),
-                estimated_total_hits: Some(0),
-                processing_time_ms: Some(0),
-            }));
-        }
+            (serde_json::json!([]), Some(0u64), Some(0u64))
+        } else {
             return Err(ApiError::internal(format!("meili error: {body}")));
         }
-
-    let payload: serde_json::Value = response
-        .json()
-        .await
+    } else {
+        let payload: serde_json::Value = meili_resp.json().await
             .map_err(|e| ApiError::internal(format!("invalid meili response: {e}")))?;
+        (
+            payload.get("hits").cloned().unwrap_or_else(|| serde_json::json!([])),
+            payload.get("estimatedTotalHits").and_then(|v| v.as_u64()),
+            payload.get("processingTimeMs").and_then(|v| v.as_u64()),
+        )
+    };
+
+    // Traitement séries
+    let series_hits: Vec<SeriesHit> = series_rows
+        .unwrap_or_default()
+        .iter()
+        .map(|row| SeriesHit {
+            library_id: row.get("library_id"),
+            name: row.get("name"),
+            book_count: row.get("book_count"),
+            books_read_count: row.get("books_read_count"),
+            first_book_id: row.get("first_book_id"),
+        })
+        .collect();
 
     Ok(Json(SearchResponse {
-        hits: payload.get("hits").cloned().unwrap_or_else(|| serde_json::json!([])),
-        estimated_total_hits: payload.get("estimatedTotalHits").and_then(|v| v.as_u64()),
-        processing_time_ms: payload.get("processingTimeMs").and_then(|v| v.as_u64()),
+        hits,
+        series_hits,
+        estimated_total_hits,
+        processing_time_ms,
     }))
 }

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: "triangle".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 {
@@ -170,3 +170,35 @@ pub async fn revoke_token(
 
     Ok(Json(serde_json::json!({"revoked": true, "id": id})))
 }
+
+/// Permanently delete a revoked API token
+#[utoipa::path(
+    post,
+    path = "/admin/tokens/{id}/delete",
+    tag = "tokens",
+    params(
+        ("id" = String, Path, description = "Token UUID"),
+    ),
+    responses(
+        (status = 200, description = "Token permanently deleted"),
+        (status = 404, description = "Token not found or not revoked"),
+        (status = 401, description = "Unauthorized"),
+        (status = 403, description = "Forbidden - Admin scope required"),
+    ),
+    security(("Bearer" = []))
+)]
+pub async fn delete_token(
+    State(state): State<AppState>,
+    Path(id): Path<Uuid>,
+) -> Result<Json<serde_json::Value>, ApiError> {
+    let result = sqlx::query("DELETE FROM api_tokens WHERE id = $1 AND revoked_at IS NOT NULL")
+        .bind(id)
+        .execute(&state.pool)
+        .await?;
+
+    if result.rows_affected() == 0 {
+        return Err(ApiError::not_found("token not found or not revoked"));
+    }
+
+    Ok(Json(serde_json::json!({"deleted": true, "id": id})))
+}

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)
+  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") || "";
 
-  // 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}`);
+    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);
 
-  // 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 response = await fetch(apiUrl.toString(), {
-      headers: {
-        Authorization: `Bearer ${token}`,
-      },
+      headers: { Authorization: `Bearer ${token}` },
     });
     
     if (!response.ok) {

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

@@ -0,0 +1,17 @@
+import { NextRequest, NextResponse } from "next/server";
+import { updateReadingProgress } from "@/lib/api";
+
+export async function PATCH(
+  request: NextRequest,
+  { params }: { params: Promise<{ bookId: string }> }
+) {
+  const { bookId } = await params;
+  try {
+    const body = await request.json();
+    const data = await updateReadingProgress(bookId, body.status, body.current_page ?? undefined);
+    return NextResponse.json(data);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Failed to update reading progress";
+    return NextResponse.json({ error: message }, { status: 500 });
+  }
+}

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,19 +1,12 @@
 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) {
@@ -22,18 +15,18 @@ export async function GET(
       
       let lastData: string | null = null;
       let isActive = true;
+      let consecutiveErrors = 0;
 
       const fetchJob = async () => {
         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) {
+            consecutiveErrors = 0;
             const data = await response.json();
             const dataStr = JSON.stringify(data);
 
@@ -63,7 +56,11 @@ export async function GET(
           }
         } catch (error) {
           if (isActive) {
-            console.error("SSE fetch error:", error);
+            consecutiveErrors++;
+            // Only log first failure and every 60th to avoid spam
+            if (consecutiveErrors === 1 || consecutiveErrors % 60 === 0) {
+              console.warn(`SSE fetch error (${consecutiveErrors} consecutive):`, error);
+            }
           }
         }
       };

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,15 +1,8 @@
 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) {
@@ -17,18 +10,18 @@ export async function GET(request: NextRequest) {
       
       let lastData: string | null = null;
       let isActive = true;
+      let consecutiveErrors = 0;
 
       const fetchJobs = async () => {
         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) {
+            consecutiveErrors = 0;
             const data = await response.json();
             const dataStr = JSON.stringify(data);
 
@@ -47,7 +40,11 @@ export async function GET(request: NextRequest) {
           }
         } catch (error) {
           if (isActive) {
-            console.error("SSE fetch error:", error);
+            consecutiveErrors++;
+            // Only log first failure and every 30th to avoid spam
+            if (consecutiveErrors === 1 || consecutiveErrors % 30 === 0) {
+              console.warn(`SSE fetch error (${consecutiveErrors} consecutive):`, error);
+            }
           }
         }
       };

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/series/mark-read/route.ts

@@ -0,0 +1,13 @@
+import { NextRequest, NextResponse } from "next/server";
+import { markSeriesRead } from "@/lib/api";
+
+export async function POST(request: NextRequest) {
+  try {
+    const body = await request.json();
+    const data = await markSeriesRead(body.series, body.status ?? "read");
+    return NextResponse.json(data);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Failed to mark series";
+    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 }> }
 ) {
-  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();
+  try {
+    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 }> }
 ) {
-  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();
+  try {
+    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,44 @@
-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 { MarkBookReadButton } from "../../components/MarkBookReadButton";
 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 +103,20 @@ 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>
+                  <div className="flex items-center gap-3">
+                    <ReadingStatusBadge
+                      status={book.reading_status}
+                      currentPage={book.reading_current_page ?? null}
+                      lastReadAt={book.reading_last_read_at ?? null}
+                    />
+                    <MarkBookReadButton bookId={book.id} currentStatus={book.reading_status} />
+                  </div>
+                </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 +162,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>
+                  <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 +208,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/books/page.tsx

@@ -1,7 +1,9 @@
-import { fetchBooks, searchBooks, fetchLibraries, BookDto, LibraryDto, getBookCoverUrl } from "../../lib/api";
+import { fetchBooks, searchBooks, fetchLibraries, BookDto, LibraryDto, SeriesHitDto, getBookCoverUrl } from "../../lib/api";
 import { BooksGrid, EmptyState } from "../components/BookCard";
-import { Card, CardContent, Button, FormField, FormInput, FormSelect, FormRow, CursorPagination } from "../components/ui";
+import { LiveSearchForm } from "../components/LiveSearchForm";
+import { Card, CardContent, OffsetPagination } from "../components/ui";
 import Link from "next/link";
+import Image from "next/image";
 
 export const dynamic = "force-dynamic";
 
@@ -13,7 +15,8 @@ export default async function BooksPage({
   const searchParamsAwaited = await searchParams;
   const libraryId = typeof searchParamsAwaited.library === "string" ? searchParamsAwaited.library : undefined;
   const searchQuery = typeof searchParamsAwaited.q === "string" ? searchParamsAwaited.q : "";
-  const cursor = typeof searchParamsAwaited.cursor === "string" ? searchParamsAwaited.cursor : undefined;
+  const readingStatus = typeof searchParamsAwaited.status === "string" ? searchParamsAwaited.status : undefined;
+  const page = typeof searchParamsAwaited.page === "string" ? parseInt(searchParamsAwaited.page) : 1;
   const limit = typeof searchParamsAwaited.limit === "string" ? parseInt(searchParamsAwaited.limit) : 20;
 
   const [libraries] = await Promise.all([
@@ -21,13 +24,15 @@ export default async function BooksPage({
   ]);
 
   let books: BookDto[] = [];
-  let nextCursor: string | null = null;
+  let total = 0;
   let searchResults: BookDto[] | null = null;
+  let seriesHits: SeriesHitDto[] = [];
   let totalHits: number | null = null;
 
   if (searchQuery) {
     const searchResponse = await searchBooks(searchQuery, libraryId, limit).catch(() => null);
     if (searchResponse) {
+      seriesHits = searchResponse.series_hits ?? [];
       searchResults = searchResponse.hits.map(hit => ({
         id: hit.id,
         library_id: hit.library_id,
@@ -41,18 +46,22 @@ export default async function BooksPage({
         file_path: null,
         file_format: null,
         file_parse_status: null,
-        updated_at: ""
+        updated_at: "",
+        reading_status: "unread" as const,
+        reading_current_page: null,
+        reading_last_read_at: null,
       }));
       totalHits = searchResponse.estimated_total_hits;
     }
   } else {
-    const booksPage = await fetchBooks(libraryId, undefined, cursor, limit).catch(() => ({ 
+    const booksPage = await fetchBooks(libraryId, undefined, page, limit, readingStatus).catch(() => ({
       items: [] as BookDto[],
-      next_cursor: null,
-      prev_cursor: null 
+      total: 0,
+      page: 1,
+      limit,
     }));
     books = booksPage.items;
-    nextCursor = booksPage.next_cursor;
+    total = booksPage.total;
   }
 
   const displayBooks = (searchResults || books).map(book => ({
@@ -60,8 +69,21 @@ export default async function BooksPage({
     coverUrl: getBookCoverUrl(book.id)
   }));
 
-  const hasNextPage = !!nextCursor;
-  const hasPrevPage = !!cursor;
+  const totalPages = Math.ceil(total / limit);
+
+  const libraryOptions = [
+    { value: "", label: "All libraries" },
+    ...libraries.map((lib) => ({ value: lib.id, label: lib.name })),
+  ];
+
+  const statusOptions = [
+    { value: "", label: "All" },
+    { value: "unread", label: "Unread" },
+    { value: "reading", label: "In progress" },
+    { value: "read", label: "Read" },
+  ];
+
+  const hasFilters = searchQuery || libraryId || readingStatus;
 
   return (
     <>
@@ -74,80 +96,78 @@ export default async function BooksPage({
         </h1>
       </div>
 
-      {/* Search Bar - Style compact et propre */}
       <Card className="mb-6">
         <CardContent className="pt-6">
-          <form className="flex flex-col sm:flex-row gap-3 items-start sm:items-end">
-            <FormField className="flex-1 w-full">
-              <label className="block text-sm font-medium text-foreground mb-1.5">Search</label>
-              <FormInput 
-                name="q" 
-                placeholder="Search by title, author, series..." 
-                defaultValue={searchQuery}
-                className="w-full"
+          <LiveSearchForm
+            basePath="/books"
+            fields={[
+              { name: "q", type: "text", label: "Search", placeholder: "Search by title, author, series...", className: "flex-1 w-full" },
+              { name: "library", type: "select", label: "Library", options: libraryOptions, className: "w-full sm:w-48" },
+              { name: "status", type: "select", label: "Status", options: statusOptions, className: "w-full sm:w-40" },
+            ]}
           />
-            </FormField>
-            <FormField className="w-full sm:w-48">
-              <label className="block text-sm font-medium text-foreground mb-1.5">Library</label>
-              <FormSelect name="library" defaultValue={libraryId || ""}>
-                <option value="">All libraries</option>
-                {libraries.map((lib) => (
-                  <option key={lib.id} value={lib.id}>
-                    {lib.name}
-                  </option>
-                ))}
-              </FormSelect>
-            </FormField>
-            <div className="flex gap-2 w-full sm:w-auto">
-              <Button type="submit" className="flex-1 sm:flex-none">
-                <svg className="w-4 h-4 mr-2" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-                  <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z" />
-                </svg>
-                Search
-              </Button>
-              {searchQuery && (
-                <Link 
-                  href="/books" 
-                  className="
-                    inline-flex items-center justify-center
-                    h-10 px-4
-                    border border-input
-                    text-sm font-medium
-                    text-muted-foreground
-                    bg-background
-                    rounded-md
-                    hover:bg-accent hover:text-accent-foreground
-                    transition-colors duration-200
-                    flex-1 sm:flex-none
-                  "
-                >
-                  Clear
-                </Link>
-              )}
-            </div>
-          </form>
         </CardContent>
       </Card>
 
       {/* Résultats */}
-      {searchQuery && totalHits !== null && (
+      {searchQuery && totalHits !== null ? (
         <p className="text-sm text-muted-foreground mb-4">
           Found {totalHits} result{totalHits !== 1 ? 's' : ''} for &quot;{searchQuery}&quot;
         </p>
+      ) : !searchQuery && (
+        <p className="text-sm text-muted-foreground mb-4">
+          {total} book{total !== 1 ? 's' : ''}
+        </p>
+      )}
+
+      {/* Séries matchantes */}
+      {seriesHits.length > 0 && (
+        <div className="mb-8">
+          <h2 className="text-lg font-semibold text-foreground mb-3">Series</h2>
+          <div className="grid grid-cols-2 sm:grid-cols-3 md:grid-cols-4 lg:grid-cols-6 gap-4">
+            {seriesHits.map((s) => (
+              <Link
+                key={`${s.library_id}-${s.name}`}
+                href={`/libraries/${s.library_id}/series/${encodeURIComponent(s.name)}`}
+                className="group"
+              >
+                <div className="bg-card rounded-xl shadow-sm border border-border/60 overflow-hidden hover:shadow-md transition-shadow duration-200">
+                  <div className="aspect-[2/3] relative bg-muted/50">
+                    <Image
+                      src={getBookCoverUrl(s.first_book_id)}
+                      alt={`Cover of ${s.name}`}
+                      fill
+                      className="object-cover"
+                      unoptimized
+                    />
+                  </div>
+                  <div className="p-2">
+                    <h3 className="font-medium text-foreground truncate text-sm" title={s.name}>
+                      {s.name === "unclassified" ? "Unclassified" : s.name}
+                    </h3>
+                    <p className="text-xs text-muted-foreground mt-0.5">
+                      {s.book_count} book{s.book_count !== 1 ? 's' : ''}
+                    </p>
+                  </div>
+                </div>
+              </Link>
+            ))}
+          </div>
+        </div>
       )}
 
       {/* Grille de livres */}
       {displayBooks.length > 0 ? (
         <>
+          {searchQuery && <h2 className="text-lg font-semibold text-foreground mb-3">Books</h2>}
           <BooksGrid books={displayBooks} />
 
           {!searchQuery && (
-            <CursorPagination
-              hasNextPage={hasNextPage}
-              hasPrevPage={hasPrevPage}
+            <OffsetPagination
+              currentPage={page}
+              totalPages={totalPages}
               pageSize={limit}
-              currentCount={displayBooks.length}
-              nextCursor={nextCursor}
+              totalItems={total}
             />
           )}
         </>

apps/backoffice/app/components/BookCard.tsx

@@ -3,14 +3,32 @@
 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 }) {
   const [isLoaded, setIsLoaded] = useState(false);
+  const [hasError, setHasError] = useState(false);
+
+  if (hasError) {
+    return (
+      <div className="relative aspect-[2/3] overflow-hidden bg-muted flex items-center justify-center">
+        <svg className="w-10 h-10 text-muted-foreground/30" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+          <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M12 6.253v13m0-13C10.832 5.477 9.246 5 7.5 5S4.168 5.477 3 6.253v13C4.168 18.477 5.754 18 7.5 18s3.332.477 4.5 1.253m0-13C13.168 5.477 14.754 5 16.5 5c1.747 0 3.332.477 4.5 1.253v13C19.832 18.477 18.247 18 16.5 18c-1.746 0-3.332.477-4.5 1.253" />
+        </svg>
+      </div>
+    );
+  }
 
   return (
     <div className="relative aspect-[2/3] overflow-hidden bg-muted">
@@ -31,24 +49,36 @@ function BookImage({ src, alt }: { src: string; alt: string }) {
         }`}
         sizes="(max-width: 640px) 50vw, (max-width: 768px) 33vw, (max-width: 1024px) 25vw, 16vw"
         onLoad={() => setIsLoaded(true)}
+        onError={() => setHasError(true)}
         unoptimized
       />
     </div>
   );
 }
 
-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;
+
+  const isRead = status === "read";
 
   return (
     <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"
+      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 ${isRead ? "opacity-50" : ""}`}
     >
+      <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/JobProgress.tsx

@@ -87,8 +87,8 @@ export function JobProgress({ jobId, onComplete }: JobProgressProps) {
   const percent = progress.progress_percent ?? 0;
   const processed = progress.processed_files ?? 0;
   const total = progress.total_files ?? 0;
-  const isThumbnailsPhase = progress.status === "generating_thumbnails";
-  const unitLabel = isThumbnailsPhase ? "thumbnails" : "files";
+  const isPhase2 = progress.status === "extracting_pages" || progress.status === "generating_thumbnails";
+  const unitLabel = progress.status === "extracting_pages" ? "pages" : progress.status === "generating_thumbnails" ? "thumbnails" : "files";
 
   return (
     <div className="p-4 bg-card rounded-lg border border-border">
@@ -112,7 +112,7 @@ export function JobProgress({ jobId, onComplete }: JobProgressProps) {
         )}
       </div>
 
-      {progress.stats_json && !isThumbnailsPhase && (
+      {progress.stats_json && !isPhase2 && (
         <div className="flex flex-wrap gap-3 text-xs">
           <Badge variant="primary">Scanned: {progress.stats_json.scanned_files}</Badge>
           <Badge variant="success">Indexed: {progress.stats_json.indexed_files}</Badge>

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: {
@@ -33,7 +33,7 @@ interface JobRowProps {
 }
 
 export function JobRow({ job, libraryName, highlighted, onCancel, formatDate, formatDuration }: JobRowProps) {
-  const isActive = job.status === "running" || job.status === "pending" || job.status === "generating_thumbnails";
+  const isActive = job.status === "running" || job.status === "pending" || job.status === "extracting_pages" || job.status === "generating_thumbnails";
   const [showProgress, setShowProgress] = useState(highlighted || isActive);
 
   const handleComplete = () => {
@@ -52,13 +52,14 @@ export function JobRow({ job, libraryName, highlighted, onCancel, formatDate, fo
   const removed = job.stats_json?.removed_files ?? 0;
   const errors = job.stats_json?.errors ?? 0;
 
+  const isPhase2 = job.status === "extracting_pages" || job.status === "generating_thumbnails";
   const isThumbnailPhase = job.status === "generating_thumbnails";
   const isThumbnailJob = job.type === "thumbnail_rebuild" || job.type === "thumbnail_regenerate";
-  const hasThumbnailPhase = isThumbnailPhase || isThumbnailJob;
+  const hasThumbnailPhase = isPhase2 || isThumbnailJob;
 
-  // Files column: index-phase stats only
+  // Files column: index-phase stats only (Phase 1 discovery)
   const filesDisplay =
-    job.status === "running" && !isThumbnailPhase
+    job.status === "running" && !isPhase2
       ? job.total_files != null
         ? `${job.processed_files ?? 0}/${job.total_files}`
         : scanned > 0
@@ -70,8 +71,8 @@ export function JobRow({ job, libraryName, highlighted, onCancel, formatDate, fo
           ? `${scanned} scanned`
           : "—";
 
-  // Thumbnails column
-  const thumbInProgress = hasThumbnailPhase && (job.status === "running" || isThumbnailPhase);
+  // Thumbnails column (Phase 2: extracting_pages + generating_thumbnails)
+  const thumbInProgress = hasThumbnailPhase && (job.status === "running" || isPhase2);
   const thumbDisplay =
     thumbInProgress && job.total_files != null
       ? `${job.processed_files ?? 0}/${job.total_files}`
@@ -93,7 +94,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} />
@@ -126,7 +129,7 @@ export function JobRow({ job, libraryName, highlighted, onCancel, formatDate, fo
                 {errors > 0 && <span className="text-error">⚠ {errors}</span>}
               </div>
             )}
-            {job.status === "running" && !isThumbnailPhase && job.total_files != null && (
+            {job.status === "running" && !isPhase2 && job.total_files != null && (
               <MiniProgressBar value={job.processed_files ?? 0} max={job.total_files} className="w-24" />
             )}
           </div>
@@ -153,7 +156,7 @@ export function JobRow({ job, libraryName, highlighted, onCancel, formatDate, fo
             >
               View
             </Link>
-            {(job.status === "pending" || job.status === "running" || job.status === "generating_thumbnails") && (
+            {(job.status === "pending" || job.status === "running" || job.status === "extracting_pages" || job.status === "generating_thumbnails") && (
               <Button 
                 variant="danger" 
                 size="sm"

apps/backoffice/app/components/JobsIndicator.tsx

@@ -1,8 +1,8 @@
 "use client";
 
-import { useEffect, useState, useRef } from "react";
+import { useEffect, useState, useRef, useCallback } from "react";
+import { createPortal } from "react-dom";
 import Link from "next/link";
-import { Button } from "./ui/Button";
 import { Badge } from "./ui/Badge";
 import { ProgressBar } from "./ui/ProgressBar";
 
@@ -19,6 +19,7 @@ interface Job {
     scanned_files: number;
     indexed_files: number;
     errors: number;
+    warnings: number;
   } | null;
 }
 
@@ -46,7 +47,9 @@ const ChevronIcon = ({ className }: { className?: string }) => (
 export function JobsIndicator() {
   const [activeJobs, setActiveJobs] = useState<Job[]>([]);
   const [isOpen, setIsOpen] = useState(false);
-  const dropdownRef = useRef<HTMLDivElement>(null);
+  const buttonRef = useRef<HTMLButtonElement>(null);
+  const popinRef = useRef<HTMLDivElement>(null);
+  const [popinStyle, setPopinStyle] = useState<React.CSSProperties>({});
 
   useEffect(() => {
     const fetchActiveJobs = async () => {
@@ -66,23 +69,72 @@ export function JobsIndicator() {
     return () => clearInterval(interval);
   }, []);
 
-  // Close dropdown when clicking outside
+  // Position the popin relative to the button
+  const updatePosition = useCallback(() => {
+    if (!buttonRef.current) return;
+    const rect = buttonRef.current.getBoundingClientRect();
+    const isMobile = window.innerWidth < 640;
+
+    if (isMobile) {
+      setPopinStyle({
+        position: "fixed",
+        top: `${rect.bottom + 8}px`,
+        left: "12px",
+        right: "12px",
+      });
+    } else {
+      // Align right edge of popin with right edge of button
+      const rightEdge = window.innerWidth - rect.right;
+      setPopinStyle({
+        position: "fixed",
+        top: `${rect.bottom + 8}px`,
+        right: `${Math.max(rightEdge, 12)}px`,
+        width: "384px", // w-96
+      });
+    }
+  }, []);
+
   useEffect(() => {
+    if (!isOpen) return;
+    updatePosition();
+    window.addEventListener("resize", updatePosition);
+    window.addEventListener("scroll", updatePosition, true);
+    return () => {
+      window.removeEventListener("resize", updatePosition);
+      window.removeEventListener("scroll", updatePosition, true);
+    };
+  }, [isOpen, updatePosition]);
+
+  // Close when clicking outside
+  useEffect(() => {
+    if (!isOpen) return;
     const handleClickOutside = (event: MouseEvent) => {
-      if (dropdownRef.current && !dropdownRef.current.contains(event.target as Node)) {
+      const target = event.target as Node;
+      if (
+        buttonRef.current && !buttonRef.current.contains(target) &&
+        popinRef.current && !popinRef.current.contains(target)
+      ) {
         setIsOpen(false);
       }
     };
-
     document.addEventListener("mousedown", handleClickOutside);
     return () => document.removeEventListener("mousedown", handleClickOutside);
-  }, []);
+  }, [isOpen]);
 
-  const runningJobs = activeJobs.filter(j => j.status === "running" || j.status === "generating_thumbnails");
+  // Close on Escape
+  useEffect(() => {
+    if (!isOpen) return;
+    const handleEsc = (e: KeyboardEvent) => {
+      if (e.key === "Escape") setIsOpen(false);
+    };
+    document.addEventListener("keydown", handleEsc);
+    return () => document.removeEventListener("keydown", handleEsc);
+  }, [isOpen]);
+
+  const runningJobs = activeJobs.filter(j => j.status === "running" || j.status === "extracting_pages" || j.status === "generating_thumbnails");
   const pendingJobs = activeJobs.filter(j => j.status === "pending");
   const totalCount = activeJobs.length;
 
-  // Calculate overall progress
   const totalProgress = runningJobs.reduce((acc, job) => {
     return acc + (job.progress_percent || 0);
   }, 0) / (runningJobs.length || 1);
@@ -107,57 +159,29 @@ export function JobsIndicator() {
     );
   }
 
-  return (
-    <div className="relative" ref={dropdownRef}>
-      <button 
-        className={`
-          flex items-center gap-2 
-          px-3 py-2 
-          rounded-md 
-          font-medium text-sm 
-          transition-all duration-200
-          ${runningJobs.length > 0 
-            ? 'bg-success/10 text-success hover:bg-success/20' 
-            : 'bg-warning/10 text-warning hover:bg-warning/20'
-          }
-          ${isOpen ? 'ring-2 ring-ring ring-offset-2 ring-offset-background' : ''}
-        `}
-        onClick={() => setIsOpen(!isOpen)}
-        title={`${totalCount} active job${totalCount !== 1 ? 's' : ''}`}
-      >
-        {/* Animated spinner for running jobs */}
-        {runningJobs.length > 0 && (
-          <div className="w-4 h-4 animate-spin">
-            <SpinnerIcon className="w-4 h-4" />
-          </div>
-        )}
-        
-        {/* Icon */}
-        <JobsIcon className="w-4 h-4" />
-        
-        {/* Badge with count */}
-        <span className="flex items-center justify-center min-w-5 h-5 px-1.5 text-xs font-bold bg-current rounded-full">
-          <span className="text-background">{totalCount > 99 ? "99+" : totalCount}</span>
-        </span>
-        
-        {/* Chevron */}
-        <ChevronIcon 
-          className={`w-4 h-4 transition-transform duration-200 ${isOpen ? 'rotate-180' : ''}`} 
+  const popin = isOpen && (
+    <>
+      {/* Mobile backdrop */}
+      <div
+        className="fixed inset-0 z-[80] sm:hidden bg-background/60 backdrop-blur-sm"
+        onClick={() => setIsOpen(false)}
+        aria-hidden="true"
       />
-      </button>
 
-      {/* Popin/Dropdown with glassmorphism */}
-      {isOpen && (
-        <div className="
-          absolute right-0 top-full mt-2 w-96 
+      {/* Popin */}
+      <div
+        ref={popinRef}
+        style={popinStyle}
+        className="
+          z-[90]
           bg-popover/95 backdrop-blur-md
           rounded-xl
           shadow-elevation-2
           border border-border/60
           overflow-hidden
-          z-50
-          animate-scale-in
-        ">
+          animate-fade-in
+        "
+      >
         {/* Header */}
         <div className="flex items-center justify-between px-4 py-3 border-b border-border/60 bg-muted/50">
           <div className="flex items-center gap-3">
@@ -210,7 +234,7 @@ export function JobsIndicator() {
                   >
                     <div className="flex items-start gap-3">
                       <div className="mt-0.5">
-                          {(job.status === "running" || job.status === "generating_thumbnails") && <span className="animate-spin inline-block">⏳</span>}
+                        {(job.status === "running" || job.status === "extracting_pages" || job.status === "generating_thumbnails") && <span className="animate-spin inline-block">⏳</span>}
                         {job.status === "pending" && <span>⏸</span>}
                       </div>
 
@@ -222,7 +246,7 @@ export function JobsIndicator() {
                           </Badge>
                         </div>
 
-                          {(job.status === "running" || job.status === "generating_thumbnails") && job.progress_percent != null && (
+                        {(job.status === "running" || job.status === "extracting_pages" || job.status === "generating_thumbnails") && job.progress_percent != null && (
                           <div className="flex items-center gap-2 mt-2">
                             <MiniProgressBar value={job.progress_percent} />
                             <span className="text-xs font-medium text-muted-foreground">{job.progress_percent}%</span>
@@ -238,8 +262,11 @@ export function JobsIndicator() {
                         {job.stats_json && (
                           <div className="flex items-center gap-3 mt-1.5 text-xs text-muted-foreground">
                             <span>✓ {job.stats_json.indexed_files}</span>
+                            {(job.stats_json.warnings ?? 0) > 0 && (
+                              <span className="text-warning">⚠ {job.stats_json.warnings}</span>
+                            )}
                             {job.stats_json.errors > 0 && (
-                                <span className="text-destructive">⚠ {job.stats_json.errors}</span>
+                              <span className="text-destructive">✕ {job.stats_json.errors}</span>
                             )}
                           </div>
                         )}
@@ -257,8 +284,51 @@ export function JobsIndicator() {
           <p className="text-xs text-muted-foreground text-center">Auto-refreshing every 2s</p>
         </div>
       </div>
-      )}
+    </>
+  );
+
+  return (
+    <>
+      <button
+        ref={buttonRef}
+        className={`
+          flex items-center gap-1.5
+          p-2 sm:px-3 sm:py-2
+          rounded-md
+          font-medium text-sm
+          transition-all duration-200
+          ${runningJobs.length > 0
+            ? 'bg-success/10 text-success hover:bg-success/20'
+            : 'bg-warning/10 text-warning hover:bg-warning/20'
+          }
+          ${isOpen ? 'ring-2 ring-ring ring-offset-2 ring-offset-background' : ''}
+        `}
+        onClick={() => setIsOpen(!isOpen)}
+        title={`${totalCount} active job${totalCount !== 1 ? 's' : ''}`}
+      >
+        {/* Animated spinner for running jobs */}
+        {runningJobs.length > 0 && (
+          <div className="w-4 h-4 animate-spin">
+            <SpinnerIcon className="w-4 h-4" />
           </div>
+        )}
+
+        {/* Icon */}
+        <JobsIcon className="w-4 h-4" />
+
+        {/* Badge with count */}
+        <span className="flex items-center justify-center min-w-5 h-5 px-1.5 text-xs font-bold bg-current rounded-full">
+          <span className="text-background">{totalCount > 99 ? "99+" : totalCount}</span>
+        </span>
+
+        {/* Chevron - hidden on small screens */}
+        <ChevronIcon
+          className={`w-4 h-4 hidden sm:block transition-transform duration-200 ${isOpen ? 'rotate-180' : ''}`}
+        />
+      </button>
+
+      {typeof document !== "undefined" && createPortal(popin, document.body)}
+    </>
   );
 }
 

apps/backoffice/app/components/JobsList.tsx

@@ -85,18 +85,14 @@ export function JobsList({ initialJobs, libraries, highlightJobId }: JobsListPro
   }, []);
 
   const handleCancel = async (id: string) => {
-    try {
-      const response = await fetch(`/api/jobs/${id}/cancel`, {
-        method: "POST",
-      });
-
+    const response = await fetch(`/api/jobs/${id}/cancel`, { method: "POST" });
     if (response.ok) {
       setJobs(jobs.map(job =>
         job.id === id ? { ...job, status: "cancelled" } : job
       ));
-      }
-    } catch (error) {
-      console.error("Failed to cancel job:", error);
+    } else {
+      const data = await response.json().catch(() => ({}));
+      console.error("Failed to cancel job:", data?.error ?? response.status);
     }
   };
 

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,6 +34,7 @@ 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";
@@ -53,12 +55,15 @@ export function LibraryActions({
           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,6 +126,12 @@ export function LibraryActions({
                 </select>
               </div>
 
+              {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"

apps/backoffice/app/components/LiveSearchForm.tsx

@@ -0,0 +1,128 @@
+"use client";
+
+import { useRef, useCallback, useEffect } from "react";
+import { useRouter, useSearchParams } from "next/navigation";
+
+interface FieldDef {
+  name: string;
+  type: "text" | "select";
+  placeholder?: string;
+  label: string;
+  options?: { value: string; label: string }[];
+  className?: string;
+}
+
+interface LiveSearchFormProps {
+  fields: FieldDef[];
+  basePath: string;
+  debounceMs?: number;
+}
+
+export function LiveSearchForm({ fields, basePath, debounceMs = 300 }: LiveSearchFormProps) {
+  const router = useRouter();
+  const searchParams = useSearchParams();
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const formRef = useRef<HTMLFormElement>(null);
+
+  const buildUrl = useCallback((): string => {
+    if (!formRef.current) return basePath;
+    const formData = new FormData(formRef.current);
+    const params = new URLSearchParams();
+    for (const [key, value] of formData.entries()) {
+      const str = value.toString().trim();
+      if (str) params.set(key, str);
+    }
+    const qs = params.toString();
+    return qs ? `${basePath}?${qs}` : basePath;
+  }, [basePath]);
+
+  const navigate = useCallback((immediate: boolean) => {
+    if (timerRef.current) clearTimeout(timerRef.current);
+    if (immediate) {
+      router.replace(buildUrl() as any);
+    } else {
+      timerRef.current = setTimeout(() => {
+        router.replace(buildUrl() as any);
+      }, debounceMs);
+    }
+  }, [router, buildUrl, debounceMs]);
+
+  useEffect(() => {
+    return () => {
+      if (timerRef.current) clearTimeout(timerRef.current);
+    };
+  }, []);
+
+  const hasFilters = fields.some((f) => {
+    const val = searchParams.get(f.name);
+    return val && val.trim() !== "";
+  });
+
+  return (
+    <form
+      ref={formRef}
+      onSubmit={(e) => {
+        e.preventDefault();
+        if (timerRef.current) clearTimeout(timerRef.current);
+        router.replace(buildUrl() as any);
+      }}
+      className="flex flex-col sm:flex-row gap-3 items-start sm:items-end"
+    >
+      {fields.map((field) =>
+        field.type === "text" ? (
+          <div key={field.name} className={field.className || "flex-1 w-full"}>
+            <label className="block text-sm font-medium text-foreground mb-1.5">
+              {field.label}
+            </label>
+            <input
+              name={field.name}
+              type="text"
+              placeholder={field.placeholder}
+              defaultValue={searchParams.get(field.name) || ""}
+              onChange={() => navigate(false)}
+              className="flex h-10 w-full rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2"
+            />
+          </div>
+        ) : (
+          <div key={field.name} className={field.className || "w-full sm:w-48"}>
+            <label className="block text-sm font-medium text-foreground mb-1.5">
+              {field.label}
+            </label>
+            <select
+              name={field.name}
+              defaultValue={searchParams.get(field.name) || ""}
+              onChange={() => navigate(true)}
+              className="flex h-10 w-full rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2"
+            >
+              {field.options?.map((opt) => (
+                <option key={opt.value} value={opt.value}>
+                  {opt.label}
+                </option>
+              ))}
+            </select>
+          </div>
+        )
+      )}
+      {hasFilters && (
+        <button
+          type="button"
+          onClick={() => router.replace(basePath as any)}
+          className="
+            inline-flex items-center justify-center
+            h-10 px-4
+            border border-input
+            text-sm font-medium
+            text-muted-foreground
+            bg-background
+            rounded-md
+            hover:bg-accent hover:text-accent-foreground
+            transition-colors duration-200
+            w-full sm:w-auto
+          "
+        >
+          Clear
+        </button>
+      )}
+    </form>
+  );
+}

apps/backoffice/app/components/MarkBookReadButton.tsx

@@ -0,0 +1,64 @@
+"use client";
+
+import { useState } from "react";
+import { useRouter } from "next/navigation";
+import { Button } from "./ui";
+
+interface MarkBookReadButtonProps {
+  bookId: string;
+  currentStatus: string;
+}
+
+export function MarkBookReadButton({ bookId, currentStatus }: MarkBookReadButtonProps) {
+  const [loading, setLoading] = useState(false);
+  const router = useRouter();
+
+  const isRead = currentStatus === "read";
+  const targetStatus = isRead ? "unread" : "read";
+  const label = isRead ? "Marquer non lu" : "Marquer comme lu";
+
+  const handleClick = async () => {
+    setLoading(true);
+    try {
+      const res = await fetch(`/api/books/${bookId}/progress`, {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ status: targetStatus }),
+      });
+      if (!res.ok) {
+        const body = await res.json().catch(() => ({ error: res.statusText }));
+        console.error("Failed to update reading progress:", body.error);
+      }
+      router.refresh();
+    } catch (err) {
+      console.error("Failed to update reading progress:", err);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <Button
+      variant={isRead ? "outline" : "primary"}
+      size="sm"
+      onClick={handleClick}
+      disabled={loading}
+    >
+      {loading ? (
+        <svg className="w-4 h-4 animate-spin" fill="none" viewBox="0 0 24 24">
+          <circle className="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="4" />
+          <path className="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4z" />
+        </svg>
+      ) : isRead ? (
+        <svg className="w-4 h-4 mr-1.5" fill="none" stroke="currentColor" viewBox="0 0 24 24" strokeWidth={2}>
+          <path strokeLinecap="round" strokeLinejoin="round" d="M9 15 3 9m0 0 6-6M3 9h12a6 6 0 0 1 0 12h-3" />
+        </svg>
+      ) : (
+        <svg className="w-4 h-4 mr-1.5" fill="none" stroke="currentColor" viewBox="0 0 24 24" strokeWidth={2}>
+          <path strokeLinecap="round" strokeLinejoin="round" d="M9 12.75 11.25 15 15 9.75M21 12a9 9 0 1 1-18 0 9 9 0 0 1 18 0z" />
+        </svg>
+      )}
+      {!loading && label}
+    </Button>
+  );
+}

apps/backoffice/app/components/MarkSeriesReadButton.tsx

@@ -0,0 +1,74 @@
+"use client";
+
+import { useState } from "react";
+import { useRouter } from "next/navigation";
+
+interface MarkSeriesReadButtonProps {
+  seriesName: string;
+  bookCount: number;
+  booksReadCount: number;
+}
+
+export function MarkSeriesReadButton({ seriesName, bookCount, booksReadCount }: MarkSeriesReadButtonProps) {
+  const [loading, setLoading] = useState(false);
+  const router = useRouter();
+
+  const allRead = booksReadCount >= bookCount;
+  const targetStatus = allRead ? "unread" : "read";
+  const label = allRead ? "Marquer non lu" : "Tout marquer lu";
+
+  const handleClick = async (e: React.MouseEvent) => {
+    e.preventDefault();
+    e.stopPropagation();
+    setLoading(true);
+    try {
+      const res = await fetch("/api/series/mark-read", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ series: seriesName, status: targetStatus }),
+      });
+      if (!res.ok) {
+        const body = await res.json().catch(() => ({ error: res.statusText }));
+        console.error("Failed to mark series:", body.error);
+      }
+      router.refresh();
+    } catch (err) {
+      console.error("Failed to mark series:", err);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <button
+      onClick={handleClick}
+      disabled={loading}
+      className={`inline-flex items-center gap-1 text-xs px-2 py-1 rounded-full font-medium transition-colors ${
+        allRead
+          ? "bg-green-500/15 text-green-600 dark:text-green-400 hover:bg-green-500/25"
+          : "bg-muted/50 text-muted-foreground hover:bg-primary/10 hover:text-primary"
+      } disabled:opacity-50`}
+    >
+      {loading ? (
+        <svg className="w-3.5 h-3.5 animate-spin" fill="none" viewBox="0 0 24 24">
+          <circle className="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="4" />
+          <path className="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4z" />
+        </svg>
+      ) : allRead ? (
+        <>
+          <svg className="w-3.5 h-3.5" fill="none" stroke="currentColor" viewBox="0 0 24 24" strokeWidth={2}>
+            <path strokeLinecap="round" strokeLinejoin="round" d="M9 15 3 9m0 0 6-6M3 9h12a6 6 0 0 1 0 12h-3" />
+          </svg>
+          {label}
+        </>
+      ) : (
+        <>
+          <svg className="w-3.5 h-3.5" fill="none" stroke="currentColor" viewBox="0 0 24 24" strokeWidth={2}>
+            <path strokeLinecap="round" strokeLinejoin="round" d="M9 12.75 11.25 15 15 9.75M21 12a9 9 0 1 1-18 0 9 9 0 0 1 18 0z" />
+          </svg>
+          {label}
+        </>
+      )}
+    </button>
+  );
+}

apps/backoffice/app/components/MobileNav.tsx

@@ -0,0 +1,104 @@
+"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" | "/series" | "/libraries" | "/jobs" | "/tokens" | "/settings";
+  label: string;
+  icon: "dashboard" | "books" | "series" | "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>
+          ))}
+
+          <div className="border-t border-border/40 mt-2 pt-2">
+            <Link
+              href="/settings"
+              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="settings" />
+              <span className="font-medium">Settings</span>
+            </Link>
+          </div>
+        </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

@@ -60,6 +60,7 @@ export function Badge({ children, variant = "default", className = "" }: BadgePr
 // Status badge for jobs/tasks
 const statusVariants: Record<string, BadgeVariant> = {
   running: "in-progress",
+  extracting_pages: "in-progress",
   generating_thumbnails: "in-progress",
   success: "completed",
   completed: "completed",
@@ -70,6 +71,7 @@ const statusVariants: Record<string, BadgeVariant> = {
 };
 
 const statusLabels: Record<string, string> = {
+  extracting_pages: "Extracting pages",
   generating_thumbnails: "Thumbnails",
 };
 
@@ -94,8 +96,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/components/ui/Form.tsx

@@ -90,7 +90,7 @@ interface FormRowProps {
 }
 
 export function FormRow({ children, className = "" }: FormRowProps) {
-  return <div className={`flex flex-wrap items-end gap-4 ${className}`}>{children}</div>;
+  return <div className={`flex flex-wrap items-start gap-4 ${className}`}>{children}</div>;
 }
 
 // Form Section

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

@@ -13,11 +13,14 @@ 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;
+  generating_thumbnails_started_at: string | null;
   current_file: string | null;
   progress_percent: number | null;
   processed_files: number | null;
@@ -27,6 +30,7 @@ interface JobDetails {
     indexed_files: number;
     removed_files: number;
     errors: number;
+    warnings: number;
   } | null;
   error_opt: string | null;
 }
@@ -38,6 +42,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}`);
@@ -64,10 +96,9 @@ function formatDuration(start: string, end: string | null): string {
   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,10 +112,50 @@ 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 isExtractingPages = job.status === "extracting_pages";
+  const isThumbnailPhase = job.status === "generating_thumbnails";
+  const isPhase2 = isExtractingPages || isThumbnailPhase;
+  const { isThumbnailOnly } = typeInfo;
+
+  // Which label to use for the progress card
+  const progressTitle = isThumbnailOnly
+    ? "Thumbnails"
+    : isExtractingPages
+      ? "Phase 2 — Extracting pages"
+      : isThumbnailPhase
+        ? "Phase 2 — Thumbnails"
+        : "Phase 1 — Discovery";
+
+  const progressDescription = isThumbnailOnly
+    ? undefined
+    : isExtractingPages
+      ? "Extracting first page from each archive (page count + raw image)"
+      : 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" || isPhase2) &&
+    (job.total_files != null || !!job.current_file);
+
   return (
     <>
       <div className="mb-6">
@@ -100,11 +171,73 @@ 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.warnings ?? 0) > 0 && `, ${job.stats_json.warnings} warnings`}
+                {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 +246,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>
+              <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 +286,223 @@ export default async function JobDetailPage({ params }: JobDetailPageProps) {
           <CardHeader>
             <CardTitle>Timeline</CardTitle>
           </CardHeader>
-          <CardContent className="space-y-4">
+          <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-2 h-2 rounded-full mt-2 ${job.created_at ? 'bg-success' : 'bg-muted'}`} />
-              <div className="flex-1">
+                  <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-sm text-muted-foreground">{new Date(job.created_at).toLocaleString()}</p>
+                    <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-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..."}
+                    <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`}
+                            {(job.stats_json.warnings ?? 0) > 0 && `, ${job.stats_json.warnings} warn`}
+                          </span>
+                        )}
                       </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>
                 )}
+
+                {/* Phase 2a — Extracting pages (index jobs with phase2) */}
+                {job.phase2_started_at && !isThumbnailOnly && (
+                  <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.generating_thumbnails_started_at || job.finished_at ? "bg-primary" : "bg-primary animate-pulse"
+                    }`} />
+                    <div className="flex-1 min-w-0">
+                      <span className="text-sm font-medium text-foreground">Phase 2a — Extracting pages</span>
+                      <p className="text-xs text-muted-foreground">{new Date(job.phase2_started_at).toLocaleString()}</p>
+                      <p className="text-xs text-primary/80 font-medium mt-0.5">
+                        Duration: {formatDuration(job.phase2_started_at, job.generating_thumbnails_started_at ?? job.finished_at ?? null)}
+                        {!job.generating_thumbnails_started_at && !job.finished_at && isExtractingPages && (
+                          <span className="text-muted-foreground font-normal ml-1">· in progress</span>
+                        )}
+                      </p>
+                    </div>
+                  </div>
+                )}
+
+                {/* Phase 2b — Generating thumbnails */}
+                {(job.generating_thumbnails_started_at || (job.phase2_started_at && isThumbnailOnly)) && (
+                  <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 2b — Generating thumbnails"}
+                      </span>
+                      <p className="text-xs text-muted-foreground">
+                        {(job.generating_thumbnails_started_at ? new Date(job.generating_thumbnails_started_at) : job.phase2_started_at ? new Date(job.phase2_started_at) : null)?.toLocaleString()}
+                      </p>
+                      {(job.generating_thumbnails_started_at || job.finished_at) && (
+                        <p className="text-xs text-primary/80 font-medium mt-0.5">
+                          Duration: {formatDuration(
+                            job.generating_thumbnails_started_at ?? job.phase2_started_at!,
+                            job.finished_at ?? null
+                          )}
+                          {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>
+                      )}
+                      {!job.finished_at && isThumbnailPhase && (
+                        <span className="text-xs text-muted-foreground">in progress</span>
+                      )}
+                    </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>
           </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 || isPhase2 ? "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-5 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.warnings ?? 0} label="Warnings" variant={(job.stats_json.warnings ?? 0) > 0 ? "warning" : "default"} />
                 <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 +515,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/jobs/page.tsx

@@ -2,7 +2,7 @@ import { revalidatePath } from "next/cache";
 import { redirect } from "next/navigation";
 import { listJobs, fetchLibraries, rebuildIndex, rebuildThumbnails, regenerateThumbnails, IndexJobDto, LibraryDto } from "../../lib/api";
 import { JobsList } from "../components/JobsList";
-import { Card, CardHeader, CardTitle, CardDescription, CardContent, Button, FormField, FormSelect, FormRow } from "../components/ui";
+import { Card, CardHeader, CardTitle, CardContent, Button, FormField, FormSelect, FormRow } from "../components/ui";
 
 export const dynamic = "force-dynamic";
 
@@ -61,90 +61,44 @@ export default async function JobsPage({ searchParams }: { searchParams: Promise
       <Card className="mb-6">
         <CardHeader>
           <CardTitle>Queue New Job</CardTitle>
-          <CardDescription>Rebuild index, full rebuild, generate missing thumbnails, or regenerate all thumbnails</CardDescription>
         </CardHeader>
-        <CardContent className="space-y-4">
-          <form action={triggerRebuild}>
+        <CardContent>
+          <form>
             <FormRow>
-              <FormField className="flex-1">
+              <FormField className="flex-1 max-w-xs">
                 <FormSelect name="library_id" defaultValue="">
                   <option value="">All libraries</option>
                   {libraries.map((lib) => (
-                    <option key={lib.id} value={lib.id}>
-                      {lib.name}
-                    </option>
+                    <option key={lib.id} value={lib.id}>{lib.name}</option>
                   ))}
                 </FormSelect>
               </FormField>
-              <Button type="submit">
+              <div className="flex flex-wrap gap-2">
+                <Button type="submit" formAction={triggerRebuild}>
                   <svg className="w-4 h-4 mr-2" fill="none" stroke="currentColor" viewBox="0 0 24 24">
                     <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M4 4v5h.582m15.356 2A8.001 8.001 0 004.582 9m0 0H9m11 11v-5h-.581m0 0a8.003 8.003 0 01-15.357-2m15.357 2H15" />
                   </svg>
-                Queue Rebuild
+                  Rebuild
                 </Button>
-            </FormRow>
-          </form>
-          
-          <form action={triggerFullRebuild}>
-            <FormRow>
-              <FormField className="flex-1">
-                <FormSelect name="library_id" defaultValue="">
-                  <option value="">All libraries</option>
-                  {libraries.map((lib) => (
-                    <option key={lib.id} value={lib.id}>
-                      {lib.name}
-                    </option>
-                  ))}
-                </FormSelect>
-              </FormField>
-              <Button type="submit" variant="warning">
+                <Button type="submit" formAction={triggerFullRebuild} variant="warning">
                   <svg className="w-4 h-4 mr-2" fill="none" stroke="currentColor" viewBox="0 0 24 24">
                     <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M19 7l-.867 12.142A2 2 0 0116.138 21H7.862a2 2 0 01-1.995-1.858L5 7m5 4v6m4-6v6m1-10V4a1 1 0 00-1-1h-4a1 1 0 00-1 1v3M4 7h16" />
                   </svg>
                   Full Rebuild
                 </Button>
-            </FormRow>
-          </form>
-
-          <form action={triggerThumbnailsRebuild}>
-            <FormRow>
-              <FormField className="flex-1">
-                <FormSelect name="library_id" defaultValue="">
-                  <option value="">All libraries</option>
-                  {libraries.map((lib) => (
-                    <option key={lib.id} value={lib.id}>
-                      {lib.name}
-                    </option>
-                  ))}
-                </FormSelect>
-              </FormField>
-              <Button type="submit" variant="secondary">
+                <Button type="submit" formAction={triggerThumbnailsRebuild} variant="secondary">
                   <svg className="w-4 h-4 mr-2" fill="none" stroke="currentColor" viewBox="0 0 24 24">
                     <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M4 16l4.586-4.586a2 2 0 012.828 0L16 16m-2-2l1.586-1.586a2 2 0 012.828 0L20 14m-6-6h.01M6 20h12a2 2 0 002-2V6a2 2 0 00-2-2H6a2 2 0 00-2 2v12a2 2 0 002 2z" />
                   </svg>
                   Generate thumbnails
                 </Button>
-            </FormRow>
-          </form>
-
-          <form action={triggerThumbnailsRegenerate}>
-            <FormRow>
-              <FormField className="flex-1">
-                <FormSelect name="library_id" defaultValue="">
-                  <option value="">All libraries</option>
-                  {libraries.map((lib) => (
-                    <option key={lib.id} value={lib.id}>
-                      {lib.name}
-                    </option>
-                  ))}
-                </FormSelect>
-              </FormField>
-              <Button type="submit" variant="warning">
+                <Button type="submit" formAction={triggerThumbnailsRegenerate} variant="warning">
                   <svg className="w-4 h-4 mr-2" fill="none" stroke="currentColor" viewBox="0 0 24 24">
                     <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M4 4v5h.582m15.356 2A8.001 8.001 0 004.582 9m0 0H9m11 11v-5h-.581m0 0a8.003 8.003 0 01-15.357-2m15.357 2H15" />
                   </svg>
                   Regenerate thumbnails
                 </Button>
+              </div>
             </FormRow>
           </form>
         </CardContent>

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",
@@ -14,14 +15,15 @@ export const metadata: Metadata = {
 };
 
 type NavItem = {
-  href: "/" | "/books" | "/libraries" | "/jobs" | "/tokens" | "/settings";
+  href: "/" | "/books" | "/series" | "/libraries" | "/jobs" | "/tokens" | "/settings";
   label: string;
-  icon: "dashboard" | "books" | "libraries" | "jobs" | "tokens" | "settings";
+  icon: "dashboard" | "books" | "series" | "libraries" | "jobs" | "tokens" | "settings";
 };
 
 const navItems: NavItem[] = [
   { href: "/", label: "Dashboard", icon: "dashboard" },
   { href: "/books", label: "Books", icon: "books" },
+  { href: "/series", label: "Series", icon: "series" },
   { href: "/libraries", label: "Libraries", icon: "libraries" },
   { href: "/jobs", label: "Jobs", icon: "jobs" },
   { href: "/tokens", label: "Tokens", icon: "tokens" },
@@ -51,7 +53,7 @@ export default function RootLayout({ children }: { children: ReactNode }) {
                   <span className="text-xl font-bold tracking-tight text-foreground">
                     StripStream
                   </span>
-                  <span className="text-sm text-muted-foreground font-medium">
+                  <span className="text-sm text-muted-foreground font-medium hidden md:inline">
                     backoffice
                   </span>
                 </div>
@@ -61,9 +63,9 @@ 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}>
+                    <NavLink key={item.href} href={item.href} title={item.label}>
                       <NavIcon name={item.icon} />
-                      <span className="ml-2">{item.label}</span>
+                      <span className="ml-2 hidden lg:inline">{item.label}</span>
                     </NavLink>
                   ))}
                 </div>
@@ -73,12 +75,13 @@ export default function RootLayout({ children }: { children: ReactNode }) {
                   <JobsIndicator />
                   <Link
                     href="/settings"
-                    className="p-2 rounded-lg text-muted-foreground hover:text-foreground hover:bg-accent transition-colors"
+                    className="hidden md:flex p-2 rounded-lg text-muted-foreground hover:text-foreground hover:bg-accent transition-colors"
                     title="Settings"
                   >
                     <Icon name="settings" size="md" />
                   </Link>
                   <ThemeToggle />
+                  <MobileNav navItems={navItems} />
                 </div>
               </div>
             </nav>
@@ -95,13 +98,14 @@ 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
       href={href}
+      title={title}
       className="
         flex items-center
-        px-3 py-2 
+        px-2 lg:px-3 py-2
         rounded-lg
         text-sm font-medium
         text-muted-foreground

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

@@ -1,7 +1,7 @@
 import { fetchLibraries, fetchBooks, getBookCoverUrl, LibraryDto, BookDto } from "../../../../lib/api";
 import { BooksGrid, EmptyState } from "../../../components/BookCard";
 import { LibrarySubPageHeader } from "../../../components/LibrarySubPageHeader";
-import { CursorPagination } from "../../../components/ui";
+import { OffsetPagination } from "../../../components/ui";
 import { notFound } from "next/navigation";
 
 export const dynamic = "force-dynamic";
@@ -15,15 +15,17 @@ export default async function LibraryBooksPage({
 }) {
   const { id } = await params;
   const searchParamsAwaited = await searchParams;
-  const cursor = typeof searchParamsAwaited.cursor === "string" ? searchParamsAwaited.cursor : undefined;
+  const page = typeof searchParamsAwaited.page === "string" ? parseInt(searchParamsAwaited.page) : 1;
   const series = typeof searchParamsAwaited.series === "string" ? searchParamsAwaited.series : undefined;
   const limit = typeof searchParamsAwaited.limit === "string" ? parseInt(searchParamsAwaited.limit) : 20;
 
   const [library, booksPage] = await Promise.all([
     fetchLibraries().then(libs => libs.find(l => l.id === id)),
-    fetchBooks(id, series, cursor, limit).catch(() => ({ 
+    fetchBooks(id, series, page, limit).catch(() => ({
       items: [] as BookDto[],
-      next_cursor: null 
+      total: 0,
+      page: 1,
+      limit,
     }))
   ]);
 
@@ -35,11 +37,9 @@ export default async function LibraryBooksPage({
     ...book,
     coverUrl: getBookCoverUrl(book.id)
   }));
-  const nextCursor = booksPage.next_cursor;
 
   const seriesDisplayName = series === "unclassified" ? "Unclassified" : series;
-  const hasNextPage = !!nextCursor;
-  const hasPrevPage = !!cursor;
+  const totalPages = Math.ceil(booksPage.total / limit);
 
   return (
     <div className="space-y-6">
@@ -63,12 +63,11 @@ export default async function LibraryBooksPage({
         <>
           <BooksGrid books={books} />
           
-          <CursorPagination
-            hasNextPage={hasNextPage}
-            hasPrevPage={hasPrevPage}
+          <OffsetPagination
+            currentPage={page}
+            totalPages={totalPages}
             pageSize={limit}
-            currentCount={books.length}
-            nextCursor={nextCursor}
+            totalItems={booksPage.total}
           />
         </>
       ) : (

apps/backoffice/app/libraries/[id]/series/[name]/page.tsx

@@ -0,0 +1,138 @@
+import { fetchLibraries, fetchBooks, getBookCoverUrl, BookDto } from "../../../../../lib/api";
+import { BooksGrid, EmptyState } from "../../../../components/BookCard";
+import { MarkSeriesReadButton } from "../../../../components/MarkSeriesReadButton";
+import { MarkBookReadButton } from "../../../../components/MarkBookReadButton";
+import { OffsetPagination } from "../../../../components/ui";
+import Image from "next/image";
+import Link from "next/link";
+import { notFound } from "next/navigation";
+
+export const dynamic = "force-dynamic";
+
+export default async function SeriesDetailPage({
+  params,
+  searchParams,
+}: {
+  params: Promise<{ id: string; name: string }>;
+  searchParams: Promise<{ [key: string]: string | string[] | undefined }>;
+}) {
+  const { id, name } = await params;
+  const searchParamsAwaited = await searchParams;
+  const page = typeof searchParamsAwaited.page === "string" ? parseInt(searchParamsAwaited.page) : 1;
+  const limit = typeof searchParamsAwaited.limit === "string" ? parseInt(searchParamsAwaited.limit) : 50;
+
+  const seriesName = decodeURIComponent(name);
+
+  const [library, booksPage] = await Promise.all([
+    fetchLibraries().then((libs) => libs.find((l) => l.id === id)),
+    fetchBooks(id, seriesName, page, limit).catch(() => ({
+      items: [] as BookDto[],
+      total: 0,
+      page: 1,
+      limit,
+    })),
+  ]);
+
+  if (!library) {
+    notFound();
+  }
+
+  const books = booksPage.items.map((book) => ({
+    ...book,
+    coverUrl: getBookCoverUrl(book.id),
+  }));
+
+  const totalPages = Math.ceil(booksPage.total / limit);
+  const booksReadCount = booksPage.items.filter((b) => b.reading_status === "read").length;
+  const displayName = seriesName === "unclassified" ? "Non classifié" : seriesName;
+
+  // Use first book cover as series cover
+  const coverBookId = booksPage.items[0]?.id;
+
+  return (
+    <div className="space-y-6">
+      {/* Breadcrumb */}
+      <div className="flex items-center gap-2 text-sm">
+        <Link
+          href="/libraries"
+          className="text-muted-foreground hover:text-primary transition-colors"
+        >
+          Libraries
+        </Link>
+        <span className="text-muted-foreground">/</span>
+        <Link
+          href={`/libraries/${id}/series`}
+          className="text-muted-foreground hover:text-primary transition-colors"
+        >
+          {library.name}
+        </Link>
+        <span className="text-muted-foreground">/</span>
+        <span className="text-foreground font-medium">{displayName}</span>
+      </div>
+
+      {/* Series Header */}
+      <div className="flex flex-col sm:flex-row gap-6">
+        {coverBookId && (
+          <div className="flex-shrink-0">
+            <div className="w-40 aspect-[2/3] relative rounded-xl overflow-hidden shadow-card border border-border">
+              <Image
+                src={getBookCoverUrl(coverBookId)}
+                alt={`Cover of ${displayName}`}
+                fill
+                className="object-cover"
+                unoptimized
+              />
+            </div>
+          </div>
+        )}
+
+        <div className="flex-1 space-y-4">
+          <h1 className="text-3xl font-bold text-foreground">{displayName}</h1>
+
+          <div className="flex flex-wrap items-center gap-4 text-sm">
+            <span className="text-muted-foreground">
+              <span className="font-semibold text-foreground">{booksPage.total}</span> livre{booksPage.total !== 1 ? "s" : ""}
+            </span>
+            <span className="w-px h-4 bg-border" />
+            <span className="text-muted-foreground">
+              <span className="font-semibold text-foreground">{booksReadCount}</span>/{booksPage.total} lu{booksPage.total !== 1 ? "s" : ""}
+            </span>
+
+            {/* Progress bar */}
+            <div className="flex items-center gap-2 flex-1 min-w-[120px] max-w-[200px]">
+              <div className="flex-1 h-2 bg-muted rounded-full overflow-hidden">
+                <div
+                  className="h-full bg-green-500 rounded-full transition-all"
+                  style={{ width: `${booksPage.total > 0 ? (booksReadCount / booksPage.total) * 100 : 0}%` }}
+                />
+              </div>
+            </div>
+          </div>
+
+          <div className="flex items-center gap-3">
+            <MarkSeriesReadButton
+              seriesName={seriesName}
+              bookCount={booksPage.total}
+              booksReadCount={booksReadCount}
+            />
+          </div>
+        </div>
+      </div>
+
+      {/* Books Grid */}
+      {books.length > 0 ? (
+        <>
+          <BooksGrid books={books} />
+          <OffsetPagination
+            currentPage={page}
+            totalPages={totalPages}
+            pageSize={limit}
+            totalItems={booksPage.total}
+          />
+        </>
+      ) : (
+        <EmptyState message="Aucun livre dans cette série" />
+      )}
+    </div>
+  );
+}

apps/backoffice/app/libraries/[id]/series/page.tsx

@@ -1,5 +1,6 @@
 import { fetchLibraries, fetchSeries, getBookCoverUrl, LibraryDto, SeriesDto, SeriesPageDto } from "../../../../lib/api";
-import { CursorPagination } from "../../../components/ui";
+import { OffsetPagination } from "../../../components/ui";
+import { MarkSeriesReadButton } from "../../../components/MarkSeriesReadButton";
 import Image from "next/image";
 import Link from "next/link";
 import { notFound } from "next/navigation";
@@ -16,12 +17,12 @@ export default async function LibrarySeriesPage({
 }) {
   const { id } = await params;
   const searchParamsAwaited = await searchParams;
-  const cursor = typeof searchParamsAwaited.cursor === "string" ? searchParamsAwaited.cursor : undefined;
+  const page = typeof searchParamsAwaited.page === "string" ? parseInt(searchParamsAwaited.page) : 1;
   const limit = typeof searchParamsAwaited.limit === "string" ? parseInt(searchParamsAwaited.limit) : 20;
 
   const [library, seriesPage] = await Promise.all([
     fetchLibraries().then(libs => libs.find(l => l.id === id)),
-    fetchSeries(id, cursor, limit).catch(() => ({ items: [] as SeriesDto[], next_cursor: null }) as SeriesPageDto)
+    fetchSeries(id, page, limit).catch(() => ({ items: [] as SeriesDto[], total: 0, page: 1, limit }) as SeriesPageDto)
   ]);
 
   if (!library) {
@@ -29,9 +30,7 @@ export default async function LibrarySeriesPage({
   }
 
   const series = seriesPage.items;
-  const nextCursor = seriesPage.next_cursor;
-  const hasNextPage = !!nextCursor;
-  const hasPrevPage = !!cursor;
+  const totalPages = Math.ceil(seriesPage.total / limit);
 
   return (
     <div className="space-y-6">
@@ -52,10 +51,10 @@ export default async function LibrarySeriesPage({
             {series.map((s) => (
               <Link
                 key={s.name}
-                href={`/libraries/${id}/books?series=${encodeURIComponent(s.name)}`}
+                href={`/libraries/${id}/series/${encodeURIComponent(s.name)}`}
                 className="group"
               >
-                <div className="bg-card rounded-xl shadow-sm border border-border/60 overflow-hidden hover:shadow-md transition-shadow duration-200">
+                <div className={`bg-card rounded-xl shadow-sm border border-border/60 overflow-hidden hover:shadow-md transition-shadow duration-200 ${s.books_read_count >= s.book_count ? "opacity-50" : ""}`}>
                   <div className="aspect-[2/3] relative bg-muted/50">
                     <Image
                       src={getBookCoverUrl(s.first_book_id)}
@@ -69,21 +68,27 @@ export default async function LibrarySeriesPage({
                     <h3 className="font-medium text-foreground truncate text-sm" title={s.name}>
                       {s.name === "unclassified" ? "Unclassified" : s.name}
                     </h3>
-                    <p className="text-xs text-muted-foreground mt-1">
-                      {s.book_count} book{s.book_count !== 1 ? 's' : ''}
+                    <div className="flex items-center justify-between mt-1">
+                      <p className="text-xs text-muted-foreground">
+                        {s.books_read_count}/{s.book_count} lu{s.book_count !== 1 ? 's' : ''}
                       </p>
+                      <MarkSeriesReadButton
+                        seriesName={s.name}
+                        bookCount={s.book_count}
+                        booksReadCount={s.books_read_count}
+                      />
+                    </div>
                   </div>
                 </div>
               </Link>
             ))}
           </div>
           
-          <CursorPagination
-            hasNextPage={hasNextPage}
-            hasPrevPage={hasPrevPage}
+          <OffsetPagination
+            currentPage={page}
+            totalPages={totalPages}
             pageSize={limit}
-            currentCount={series.length}
-            nextCursor={nextCursor}
+            totalItems={seriesPage.total}
           />
         </>
       ) : (

apps/backoffice/app/series/page.tsx

@@ -0,0 +1,140 @@
+import { fetchAllSeries, fetchLibraries, LibraryDto, SeriesDto, SeriesPageDto, getBookCoverUrl } from "../../lib/api";
+import { MarkSeriesReadButton } from "../components/MarkSeriesReadButton";
+import { LiveSearchForm } from "../components/LiveSearchForm";
+import { Card, CardContent, OffsetPagination } from "../components/ui";
+import Image from "next/image";
+import Link from "next/link";
+
+export const dynamic = "force-dynamic";
+
+export default async function SeriesPage({
+  searchParams,
+}: {
+  searchParams: Promise<{ [key: string]: string | string[] | undefined }>;
+}) {
+  const searchParamsAwaited = await searchParams;
+  const libraryId = typeof searchParamsAwaited.library === "string" ? searchParamsAwaited.library : undefined;
+  const searchQuery = typeof searchParamsAwaited.q === "string" ? searchParamsAwaited.q : "";
+  const readingStatus = typeof searchParamsAwaited.status === "string" ? searchParamsAwaited.status : undefined;
+  const page = typeof searchParamsAwaited.page === "string" ? parseInt(searchParamsAwaited.page) : 1;
+  const limit = typeof searchParamsAwaited.limit === "string" ? parseInt(searchParamsAwaited.limit) : 20;
+
+  const [libraries, seriesPage] = await Promise.all([
+    fetchLibraries().catch(() => [] as LibraryDto[]),
+    fetchAllSeries(libraryId, searchQuery || undefined, readingStatus, page, limit).catch(
+      () => ({ items: [] as SeriesDto[], total: 0, page: 1, limit }) as SeriesPageDto
+    ),
+  ]);
+
+  const series = seriesPage.items;
+  const totalPages = Math.ceil(seriesPage.total / limit);
+  const hasFilters = searchQuery || libraryId || readingStatus;
+
+  const libraryOptions = [
+    { value: "", label: "All libraries" },
+    ...libraries.map((lib) => ({ value: lib.id, label: lib.name })),
+  ];
+
+  const statusOptions = [
+    { value: "", label: "All" },
+    { value: "unread", label: "Unread" },
+    { value: "reading", label: "In progress" },
+    { value: "read", label: "Read" },
+  ];
+
+  return (
+    <>
+      <div className="mb-6">
+        <h1 className="text-3xl font-bold text-foreground flex items-center gap-3">
+          <svg className="w-8 h-8 text-primary" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+            <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M19 11H5m14 0a2 2 0 012 2v6a2 2 0 01-2 2H5a2 2 0 01-2-2v-6a2 2 0 012-2m14 0V9a2 2 0 00-2-2M5 11V9a2 2 0 012-2m0 0V5a2 2 0 012-2h6a2 2 0 012 2v2M7 7h10" />
+          </svg>
+          Series
+        </h1>
+      </div>
+
+      <Card className="mb-6">
+        <CardContent className="pt-6">
+          <LiveSearchForm
+            basePath="/series"
+            fields={[
+              { name: "q", type: "text", label: "Search", placeholder: "Search by series name...", className: "flex-1 w-full" },
+              { name: "library", type: "select", label: "Library", options: libraryOptions, className: "w-full sm:w-48" },
+              { name: "status", type: "select", label: "Status", options: statusOptions, className: "w-full sm:w-40" },
+            ]}
+          />
+        </CardContent>
+      </Card>
+
+      {/* Results count */}
+      <p className="text-sm text-muted-foreground mb-4">
+        {seriesPage.total} series
+        {searchQuery && <> matching &quot;{searchQuery}&quot;</>}
+      </p>
+
+      {/* Series Grid */}
+      {series.length > 0 ? (
+        <>
+          <div className="grid grid-cols-2 sm:grid-cols-3 md:grid-cols-4 lg:grid-cols-5 xl:grid-cols-6 gap-4">
+            {series.map((s) => (
+              <Link
+                key={s.name}
+                href={`/libraries/${s.library_id}/series/${encodeURIComponent(s.name)}`}
+                className="group"
+              >
+                <div
+                  className={`bg-card rounded-xl shadow-sm border border-border/60 overflow-hidden hover:shadow-md hover:-translate-y-1 transition-all duration-200 ${
+                    s.books_read_count >= s.book_count ? "opacity-50" : ""
+                  }`}
+                >
+                  <div className="aspect-[2/3] relative bg-muted/50">
+                    <Image
+                      src={getBookCoverUrl(s.first_book_id)}
+                      alt={`Cover of ${s.name}`}
+                      fill
+                      className="object-cover"
+                      unoptimized
+                    />
+                  </div>
+                  <div className="p-3">
+                    <h3 className="font-medium text-foreground truncate text-sm" title={s.name}>
+                      {s.name === "unclassified" ? "Unclassified" : s.name}
+                    </h3>
+                    <div className="flex items-center justify-between mt-1">
+                      <p className="text-xs text-muted-foreground">
+                        {s.books_read_count}/{s.book_count} lu{s.book_count !== 1 ? "s" : ""}
+                      </p>
+                      <MarkSeriesReadButton
+                        seriesName={s.name}
+                        bookCount={s.book_count}
+                        booksReadCount={s.books_read_count}
+                      />
+                    </div>
+                  </div>
+                </div>
+              </Link>
+            ))}
+          </div>
+
+          <OffsetPagination
+            currentPage={page}
+            totalPages={totalPages}
+            pageSize={limit}
+            totalItems={seriesPage.total}
+          />
+        </>
+      ) : (
+        <div className="flex flex-col items-center justify-center py-16 text-center">
+          <div className="w-16 h-16 mb-4 text-muted-foreground/30">
+            <svg fill="none" stroke="currentColor" viewBox="0 0 24 24">
+              <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M19 11H5m14 0a2 2 0 012 2v6a2 2 0 01-2 2H5a2 2 0 01-2-2v-6a2 2 0 012-2m14 0V9a2 2 0 00-2-2M5 11V9a2 2 0 012-2m0 0V5a2 2 0 012-2h6a2 2 0 012 2v2M7 7h10" />
+            </svg>
+          </div>
+          <p className="text-muted-foreground text-lg">
+            {hasFilters ? "No series found matching your filters" : "No series available"}
+          </p>
+        </div>
+      )}
+    </>
+  );
+}

apps/backoffice/app/settings/SettingsPage.tsx

@@ -88,13 +88,13 @@ export default function SettingsPage({ initialSettings, initialCacheStats, initi
             <Icon name="image" size="md" />
             Image Processing
           </CardTitle>
-          <CardDescription>Configure how images are processed and compressed</CardDescription>
+          <CardDescription>These settings only apply when a client explicitly requests format conversion via the API (e.g. <code className="text-xs bg-muted px-1 rounded">?format=webp&amp;width=800</code>). Pages served without parameters are delivered as-is from the archive, with no processing.</CardDescription>
         </CardHeader>
         <CardContent>
           <div className="space-y-4">
             <FormRow>
               <FormField className="flex-1">
-                <label className="text-sm font-medium text-muted-foreground mb-1 block">Output Format</label>
+                <label className="text-sm font-medium text-muted-foreground mb-1 block">Default Output Format</label>
                 <FormSelect
                   value={settings.image_processing.format}
                   onChange={(e) => {
@@ -103,13 +103,13 @@ export default function SettingsPage({ initialSettings, initialCacheStats, initi
                     handleUpdateSetting("image_processing", newSettings.image_processing);
                   }}
                 >
-                  <option value="webp">WebP (Recommended)</option>
+                  <option value="webp">WebP</option>
                   <option value="jpeg">JPEG</option>
                   <option value="png">PNG</option>
                 </FormSelect>
               </FormField>
               <FormField className="flex-1">
-                <label className="text-sm font-medium text-muted-foreground mb-1 block">Quality (1-100)</label>
+                <label className="text-sm font-medium text-muted-foreground mb-1 block">Default Quality (1-100)</label>
                 <FormInput 
                   type="number" 
                   min={1} 
@@ -126,7 +126,7 @@ export default function SettingsPage({ initialSettings, initialCacheStats, initi
             </FormRow>
             <FormRow>
               <FormField className="flex-1">
-                <label className="text-sm font-medium text-muted-foreground mb-1 block">Resize Filter</label>
+                <label className="text-sm font-medium text-muted-foreground mb-1 block">Default Resize Filter</label>
                 <FormSelect 
                   value={settings.image_processing.filter}
                   onChange={(e) => {
@@ -141,7 +141,7 @@ export default function SettingsPage({ initialSettings, initialCacheStats, initi
                 </FormSelect>
               </FormField>
               <FormField className="flex-1">
-                <label className="text-sm font-medium text-muted-foreground mb-1 block">Max Width (px)</label>
+                <label className="text-sm font-medium text-muted-foreground mb-1 block">Max Allowed Width (px)</label>
                 <FormInput 
                   type="number" 
                   min={100} 
@@ -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>
@@ -341,10 +344,16 @@ export default function SettingsPage({ initialSettings, initialCacheStats, initi
                     handleUpdateSetting("thumbnail", newSettings.thumbnail);
                   }}
                 >
-                  <option value="webp">WebP (Recommended)</option>
+                  <option value="original">Original (No Re-encoding)</option>
+                  <option value="webp">WebP</option>
                   <option value="jpeg">JPEG</option>
                   <option value="png">PNG</option>
                 </FormSelect>
+                <p className="text-xs text-muted-foreground mt-1">
+                  {settings.thumbnail.format === "original"
+                    ? "Resizes to target dimensions, keeps source format (JPEG→JPEG). Much faster generation."
+                    : "Resizes and re-encodes to selected format."}
+                </p>
               </FormField>
             </FormRow>
             <FormRow>
@@ -424,7 +433,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>