diff --git a/docs/superpowers/plans/2026-03-15-bookstack-connector.md b/docs/superpowers/plans/2026-03-15-bookstack-connector.md
new file mode 100644
index 0000000..a13bcae
--- /dev/null
+++ b/docs/superpowers/plans/2026-03-15-bookstack-connector.md
@@ -0,0 +1,2148 @@
+# BookStack Connector Implementation Plan
+
+> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add a BookStack connector that lets users link wiki pages and books to tasks, with project-level shelf configuration and admin settings.
+
+**Architecture:** Mirrors the existing Gitea connector pattern — singleton config entity, API service, API Platform DTOs with Provider/Processor, frontend service + components. Links stored in a dedicated join table `task_bookstack_link`.
+
+**Tech Stack:** PHP 8.4 / Symfony 8 / API Platform 4 / Doctrine ORM / PostgreSQL 16 / Nuxt 4 / Vue 3 / TypeScript
+
+**Spec:** `docs/superpowers/specs/2026-03-15-bookstack-connector-design.md`
+
+---
+
+## Chunk 1: Prerequisites & Backend Foundation
+
+### Task 1: Rename GITEA_ENCRYPTION_KEY → ENCRYPTION_KEY
+
+**Files:**
+- Modify: `src/Service/TokenEncryptor.php`
+- Modify: `.env`
+
+- [ ] **Step 1: Update TokenEncryptor to use generic env var**
+
+In `src/Service/TokenEncryptor.php`, change the `#[Autowire]` attribute and error message:
+
+```php
+// Change line 19:
+#[Autowire('%env(GITEA_ENCRYPTION_KEY)%')]
+// To:
+#[Autowire('%env(ENCRYPTION_KEY)%')]
+```
+
+And update the `assertConfigured()` error message:
+
+```php
+// Change:
+throw new GiteaApiException('Gitea encryption is not configured. Please set a valid GITEA_ENCRYPTION_KEY.');
+// To:
+throw new \RuntimeException('Encryption is not configured. Please set a valid ENCRYPTION_KEY.');
+```
+
+Also update the `use` statement: replace `use App\Exception\GiteaApiException;` with `use RuntimeException;`.
+
+> **Note:** `docker/.env.docker` does not contain `GITEA_ENCRYPTION_KEY` (it may be in `docker/.env.docker.local` which is gitignored). Developers using `.env.docker.local` should update it manually.
+
+- [ ] **Step 2: Update .env**
+
+```
+# Change:
+GITEA_ENCRYPTION_KEY=aaaaaaaaa
+# To:
+ENCRYPTION_KEY=aaaaaaaaa
+```
+
+- [ ] **Step 3: Verify app still works**
+
+Run: `make cache-clear`
+Expected: No errors.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/Service/TokenEncryptor.php .env
+git commit -m "refactor : rename GITEA_ENCRYPTION_KEY to ENCRYPTION_KEY"
+```
+
+---
+
+### Task 2: BookStackConfiguration Entity
+
+**Files:**
+- Create: `src/Entity/BookStackConfiguration.php`
+- Create: `src/Repository/BookStackConfigurationRepository.php`
+
+- [ ] **Step 1: Create BookStackConfiguration entity**
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\Entity;
+
+use App\Repository\BookStackConfigurationRepository;
+use Doctrine\ORM\Mapping as ORM;
+
+#[ORM\Entity(repositoryClass: BookStackConfigurationRepository::class)]
+class BookStackConfiguration
+{
+    #[ORM\Id]
+    #[ORM\GeneratedValue]
+    #[ORM\Column]
+    private ?int $id = null;
+
+    #[ORM\Column(length: 255, nullable: true)]
+    private ?string $url = null;
+
+    #[ORM\Column(type: 'text', nullable: true)]
+    private ?string $encryptedTokenId = null;
+
+    #[ORM\Column(type: 'text', nullable: true)]
+    private ?string $encryptedTokenSecret = null;
+
+    public function getId(): ?int
+    {
+        return $this->id;
+    }
+
+    public function getUrl(): ?string
+    {
+        return $this->url;
+    }
+
+    public function setUrl(?string $url): static
+    {
+        $this->url = $url;
+
+        return $this;
+    }
+
+    public function getEncryptedTokenId(): ?string
+    {
+        return $this->encryptedTokenId;
+    }
+
+    public function setEncryptedTokenId(?string $encryptedTokenId): static
+    {
+        $this->encryptedTokenId = $encryptedTokenId;
+
+        return $this;
+    }
+
+    public function getEncryptedTokenSecret(): ?string
+    {
+        return $this->encryptedTokenSecret;
+    }
+
+    public function setEncryptedTokenSecret(?string $encryptedTokenSecret): static
+    {
+        $this->encryptedTokenSecret = $encryptedTokenSecret;
+
+        return $this;
+    }
+
+    public function hasToken(): bool
+    {
+        return null !== $this->encryptedTokenId && null !== $this->encryptedTokenSecret;
+    }
+}
+```
+
+- [ ] **Step 2: Create BookStackConfigurationRepository**
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\Repository;
+
+use App\Entity\BookStackConfiguration;
+use Doctrine\Bundle\DoctrineBundle\Repository\ServiceEntityRepository;
+use Doctrine\Persistence\ManagerRegistry;
+
+class BookStackConfigurationRepository extends ServiceEntityRepository
+{
+    public function __construct(ManagerRegistry $registry)
+    {
+        parent::__construct($registry, BookStackConfiguration::class);
+    }
+
+    public function findSingleton(): ?BookStackConfiguration
+    {
+        return $this->findOneBy([]);
+    }
+}
+```
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/Entity/BookStackConfiguration.php src/Repository/BookStackConfigurationRepository.php
+git commit -m "feat(bookstack) : add BookStackConfiguration entity and repository"
+```
+
+---
+
+### Task 3: TaskBookStackLink Entity
+
+**Files:**
+- Create: `src/Entity/TaskBookStackLink.php`
+- Create: `src/Repository/TaskBookStackLinkRepository.php`
+
+- [ ] **Step 1: Create TaskBookStackLink entity**
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\Entity;
+
+use App\Repository\TaskBookStackLinkRepository;
+use Doctrine\ORM\Mapping as ORM;
+
+#[ORM\Entity(repositoryClass: TaskBookStackLinkRepository::class)]
+#[ORM\UniqueConstraint(name: 'UNIQ_task_bookstack_link', columns: ['task_id', 'bookstack_id', 'bookstack_type'])]
+class TaskBookStackLink
+{
+    #[ORM\Id]
+    #[ORM\GeneratedValue]
+    #[ORM\Column]
+    private ?int $id = null;
+
+    #[ORM\ManyToOne(targetEntity: Task::class)]
+    #[ORM\JoinColumn(nullable: false, onDelete: 'CASCADE')]
+    private Task $task;
+
+    #[ORM\Column]
+    private int $bookstackId;
+
+    #[ORM\Column(length: 10)]
+    private string $bookstackType;
+
+    #[ORM\Column(length: 255)]
+    private string $title;
+
+    #[ORM\Column(length: 500)]
+    private string $url;
+
+    #[ORM\Column]
+    private \DateTimeImmutable $createdAt;
+
+    public function __construct()
+    {
+        $this->createdAt = new \DateTimeImmutable();
+    }
+
+    public function getId(): ?int
+    {
+        return $this->id;
+    }
+
+    public function getTask(): Task
+    {
+        return $this->task;
+    }
+
+    public function setTask(Task $task): static
+    {
+        $this->task = $task;
+
+        return $this;
+    }
+
+    public function getBookstackId(): int
+    {
+        return $this->bookstackId;
+    }
+
+    public function setBookstackId(int $bookstackId): static
+    {
+        $this->bookstackId = $bookstackId;
+
+        return $this;
+    }
+
+    public function getBookstackType(): string
+    {
+        return $this->bookstackType;
+    }
+
+    public function setBookstackType(string $bookstackType): static
+    {
+        $this->bookstackType = $bookstackType;
+
+        return $this;
+    }
+
+    public function getTitle(): string
+    {
+        return $this->title;
+    }
+
+    public function setTitle(string $title): static
+    {
+        $this->title = $title;
+
+        return $this;
+    }
+
+    public function getUrl(): string
+    {
+        return $this->url;
+    }
+
+    public function setUrl(string $url): static
+    {
+        $this->url = $url;
+
+        return $this;
+    }
+
+    public function getCreatedAt(): \DateTimeImmutable
+    {
+        return $this->createdAt;
+    }
+}
+```
+
+- [ ] **Step 2: Create TaskBookStackLinkRepository**
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\Repository;
+
+use App\Entity\TaskBookStackLink;
+use Doctrine\Bundle\DoctrineBundle\Repository\ServiceEntityRepository;
+use Doctrine\Persistence\ManagerRegistry;
+
+class TaskBookStackLinkRepository extends ServiceEntityRepository
+{
+    public function __construct(ManagerRegistry $registry)
+    {
+        parent::__construct($registry, TaskBookStackLink::class);
+    }
+
+    /** @return TaskBookStackLink[] */
+    public function findByTaskId(int $taskId): array
+    {
+        return $this->findBy(['task' => $taskId], ['createdAt' => 'DESC']);
+    }
+}
+```
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/Entity/TaskBookStackLink.php src/Repository/TaskBookStackLinkRepository.php
+git commit -m "feat(bookstack) : add TaskBookStackLink entity and repository"
+```
+
+---
+
+### Task 4: Extend Project Entity
+
+**Files:**
+- Modify: `src/Entity/Project.php`
+
+- [ ] **Step 1: Add BookStack fields to Project**
+
+After the `giteaRepo` property (around line 76), add:
+
+```php
+    #[ORM\Column(nullable: true)]
+    #[Groups(['project:read', 'project:write', 'task:read'])]
+    private ?int $bookstackShelfId = null;
+
+    #[ORM\Column(length: 255, nullable: true)]
+    #[Groups(['project:read', 'project:write'])]
+    private ?string $bookstackShelfName = null;
+```
+
+At the end of the class (before the closing `}`), add getters and setters:
+
+```php
+    public function getBookstackShelfId(): ?int
+    {
+        return $this->bookstackShelfId;
+    }
+
+    public function setBookstackShelfId(?int $bookstackShelfId): static
+    {
+        $this->bookstackShelfId = $bookstackShelfId;
+
+        return $this;
+    }
+
+    public function getBookstackShelfName(): ?string
+    {
+        return $this->bookstackShelfName;
+    }
+
+    public function setBookstackShelfName(?string $bookstackShelfName): static
+    {
+        $this->bookstackShelfName = $bookstackShelfName;
+
+        return $this;
+    }
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add src/Entity/Project.php
+git commit -m "feat(bookstack) : add bookstackShelfId and bookstackShelfName to Project"
+```
+
+---
+
+### Task 5: Generate and Run Migration
+
+**Files:**
+- Create: `migrations/VersionXXXX.php` (auto-generated)
+
+- [ ] **Step 1: Generate migration**
+
+Run inside the PHP container:
+
+```bash
+make shell
+# Then inside the container:
+php bin/console doctrine:migrations:diff
+```
+
+Verify the generated migration contains:
+- `CREATE TABLE bookstack_configuration` with `id`, `url`, `encrypted_token_id`, `encrypted_token_secret`
+- `CREATE TABLE task_bookstack_link` with `id`, `task_id`, `bookstack_id`, `bookstack_type`, `title`, `url`, `created_at`
+- Index on `task_bookstack_link.task_id`
+- Unique constraint on `(task_id, bookstack_id, bookstack_type)`
+- `ALTER TABLE project ADD bookstack_shelf_id`, `bookstack_shelf_name`
+
+- [ ] **Step 2: Run migration**
+
+```bash
+make migration-migrate
+```
+
+Expected: Migration executes successfully.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add migrations/
+git commit -m "feat(bookstack) : add migration for BookStack tables and Project columns"
+```
+
+---
+
+### Task 6: BookStackApiException
+
+**Files:**
+- Create: `src/Exception/BookStackApiException.php`
+
+- [ ] **Step 1: Create exception class**
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\Exception;
+
+use RuntimeException;
+use Throwable;
+
+final class BookStackApiException extends RuntimeException
+{
+    public function __construct(string $message, int $code = 0, ?Throwable $previous = null)
+    {
+        parent::__construct($message, $code, $previous);
+    }
+}
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add src/Exception/BookStackApiException.php
+git commit -m "feat(bookstack) : add BookStackApiException"
+```
+
+---
+
+### Task 7: BookStackApiService
+
+**Files:**
+- Create: `src/Service/BookStackApiService.php`
+
+- [ ] **Step 1: Create the API service**
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\Service;
+
+use App\Entity\BookStackConfiguration;
+use App\Exception\BookStackApiException;
+use App\Repository\BookStackConfigurationRepository;
+use Symfony\Contracts\HttpClient\Exception\ExceptionInterface;
+use Symfony\Contracts\HttpClient\Exception\HttpExceptionInterface;
+use Symfony\Contracts\HttpClient\HttpClientInterface;
+use Throwable;
+
+final class BookStackApiService
+{
+    /** @var array<int, int[]> */
+    private array $shelfBookCache = [];
+
+    public function __construct(
+        private readonly HttpClientInterface $httpClient,
+        private readonly BookStackConfigurationRepository $configRepository,
+        private readonly TokenEncryptor $tokenEncryptor,
+    ) {}
+
+    public function testConnection(): bool
+    {
+        try {
+            $this->request('GET', '/api/docs.json');
+
+            return true;
+        } catch (BookStackApiException) {
+            return false;
+        }
+    }
+
+    /**
+     * @return array<array{id: int, name: string}>
+     */
+    public function listShelves(): array
+    {
+        $result = [];
+        $offset = 0;
+        $count  = 100;
+
+        do {
+            $data = $this->request('GET', '/api/shelves', [
+                'query' => ['count' => $count, 'offset' => $offset],
+            ]);
+            $items  = $data['data'] ?? [];
+            $result = array_merge($result, $items);
+            $offset += $count;
+        } while (!empty($items) && $count === count($items));
+
+        return $result;
+    }
+
+    /**
+     * Search for pages and books within a specific shelf.
+     *
+     * Algorithm:
+     * 1. Fetch the shelf's book IDs
+     * 2. Run two search queries (one for pages, one for books)
+     * 3. Filter results: pages must belong to a book on the shelf, books must be on the shelf
+     *
+     * @return array<array{id: int, type: string, name: string, url: string}>
+     */
+    public function searchInShelf(int $shelfId, string $query): array
+    {
+        $bookIds = $this->getShelfBookIds($shelfId);
+
+        if (empty($bookIds)) {
+            return [];
+        }
+
+        $config  = $this->getConfiguration();
+        $baseUrl = rtrim($config->getUrl() ?? '', '/');
+        $trimmed = trim($query);
+
+        // BookStack search API accepts {type:X} for one type at a time — run two queries
+        $pageResults = $this->request('GET', '/api/search', [
+            'query' => ['query' => $trimmed . ' {type:page}', 'count' => 50],
+        ]);
+        $bookResults = $this->request('GET', '/api/search', [
+            'query' => ['query' => $trimmed . ' {type:book}', 'count' => 50],
+        ]);
+
+        $allResults = array_merge($pageResults['data'] ?? [], $bookResults['data'] ?? []);
+
+        // Build a map of bookId → bookSlug for URL construction
+        $shelfData = $this->request('GET', sprintf('/api/shelves/%d', $shelfId));
+        $bookSlugs = [];
+        foreach ($shelfData['books'] ?? [] as $book) {
+            $bookSlugs[$book['id']] = $book['slug'] ?? '';
+        }
+
+        $filtered = [];
+        foreach ($allResults as $item) {
+            $type = $item['type'] ?? '';
+
+            if ('page' === $type) {
+                $bookId = $item['book_id'] ?? 0;
+                if (in_array($bookId, $bookIds, true)) {
+                    $bookSlug = $bookSlugs[$bookId] ?? '';
+                    $filtered[] = [
+                        'id'   => $item['id'],
+                        'type' => 'page',
+                        'name' => $item['name'] ?? '',
+                        'url'  => $baseUrl . '/books/' . $bookSlug . '/page/' . $item['slug'],
+                    ];
+                }
+            } elseif ('book' === $type) {
+                if (in_array($item['id'], $bookIds, true)) {
+                    $filtered[] = [
+                        'id'   => $item['id'],
+                        'type' => 'book',
+                        'name' => $item['name'] ?? '',
+                        'url'  => $baseUrl . '/books/' . $item['slug'],
+                    ];
+                }
+            }
+            // Ignore chapter and bookshelf types
+        }
+
+        return $filtered;
+    }
+
+    /**
+     * @return array{id: int, name: string, slug: string}
+     */
+    public function getPage(int $id): array
+    {
+        return $this->request('GET', sprintf('/api/pages/%d', $id));
+    }
+
+    /**
+     * @return array{id: int, name: string, slug: string}
+     */
+    public function getBook(int $id): array
+    {
+        return $this->request('GET', sprintf('/api/books/%d', $id));
+    }
+
+    /**
+     * @return int[]
+     */
+    private function getShelfBookIds(int $shelfId): array
+    {
+        if (isset($this->shelfBookCache[$shelfId])) {
+            return $this->shelfBookCache[$shelfId];
+        }
+
+        $data  = $this->request('GET', sprintf('/api/shelves/%d', $shelfId));
+        $books = $data['books'] ?? [];
+
+        $ids = array_map(static fn (array $book): int => $book['id'], $books);
+        $this->shelfBookCache[$shelfId] = $ids;
+
+        return $ids;
+    }
+
+    private function getConfiguration(): BookStackConfiguration
+    {
+        $config = $this->configRepository->findSingleton();
+        if (null === $config) {
+            throw new BookStackApiException('BookStack is not configured.');
+        }
+
+        return $config;
+    }
+
+    /**
+     * @return array{tokenId: string, tokenSecret: string}
+     */
+    private function getDecryptedTokens(BookStackConfiguration $config): array
+    {
+        $encryptedId     = $config->getEncryptedTokenId();
+        $encryptedSecret = $config->getEncryptedTokenSecret();
+
+        if (null === $encryptedId || null === $encryptedSecret) {
+            throw new BookStackApiException('BookStack tokens are not set.');
+        }
+
+        try {
+            return [
+                'tokenId'     => $this->tokenEncryptor->decrypt($encryptedId),
+                'tokenSecret' => $this->tokenEncryptor->decrypt($encryptedSecret),
+            ];
+        } catch (Throwable $e) {
+            throw new BookStackApiException('Failed to decrypt BookStack tokens: ' . $e->getMessage(), 0, $e);
+        }
+    }
+
+    private function extractError(HttpExceptionInterface $e): string
+    {
+        try {
+            $body = $e->getResponse()->getContent(false);
+            $data = json_decode($body, true);
+
+            if (is_array($data)) {
+                return $data['message'] ?? $data['error'] ?? $body;
+            }
+
+            return $body ?: 'Unknown BookStack error';
+        } catch (ExceptionInterface) {
+            return 'BookStack API error (HTTP ' . $e->getResponse()->getStatusCode() . ')';
+        }
+    }
+
+    /**
+     * @param array<string, mixed> $options
+     */
+    private function request(string $method, string $path, array $options = []): array
+    {
+        $config = $this->getConfiguration();
+        $tokens = $this->getDecryptedTokens($config);
+
+        $options['headers'] = array_merge($options['headers'] ?? [], [
+            'Authorization' => sprintf('Token %s:%s', $tokens['tokenId'], $tokens['tokenSecret']),
+            'Accept'        => 'application/json',
+        ]);
+        $options['timeout'] = 10;
+
+        try {
+            $response = $this->httpClient->request($method, rtrim($config->getUrl(), '/') . $path, $options);
+
+            return $response->toArray();
+        } catch (HttpExceptionInterface $e) {
+            $message = $this->extractError($e);
+            throw new BookStackApiException($message, $e->getResponse()->getStatusCode(), $e);
+        } catch (ExceptionInterface $e) {
+            throw new BookStackApiException('BookStack API error: ' . $e->getMessage(), 0, $e);
+        }
+    }
+}
+```
+
+- [ ] **Step 2: Verify no syntax errors**
+
+Run: `make cache-clear`
+Expected: No errors.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/Service/BookStackApiService.php
+git commit -m "feat(bookstack) : add BookStackApiService"
+```
+
+---
+
+## Chunk 2: API Resources & State Providers/Processors
+
+### Task 8: BookStackSettings API Resource
+
+**Files:**
+- Create: `src/ApiResource/BookStackSettings.php`
+- Create: `src/State/BookStackSettingsProvider.php`
+- Create: `src/State/BookStackSettingsProcessor.php`
+
+- [ ] **Step 1: Create BookStackSettings DTO**
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\ApiResource;
+
+use ApiPlatform\Metadata\ApiResource;
+use ApiPlatform\Metadata\Get;
+use ApiPlatform\Metadata\Put;
+use App\State\BookStackSettingsProcessor;
+use App\State\BookStackSettingsProvider;
+use Symfony\Component\Serializer\Attribute\Groups;
+
+#[ApiResource(
+    operations: [
+        new Get(
+            uriTemplate: '/settings/bookstack',
+            normalizationContext: ['groups' => ['bookstack_settings:read']],
+            provider: BookStackSettingsProvider::class,
+            security: "is_granted('ROLE_ADMIN')",
+        ),
+        new Put(
+            uriTemplate: '/settings/bookstack',
+            denormalizationContext: ['groups' => ['bookstack_settings:write']],
+            normalizationContext: ['groups' => ['bookstack_settings:read']],
+            provider: BookStackSettingsProvider::class,
+            processor: BookStackSettingsProcessor::class,
+            security: "is_granted('ROLE_ADMIN')",
+        ),
+    ],
+)]
+final class BookStackSettings
+{
+    #[Groups(['bookstack_settings:read', 'bookstack_settings:write'])]
+    public ?string $url = null;
+
+    #[Groups(['bookstack_settings:write'])]
+    public ?string $tokenId = null;
+
+    #[Groups(['bookstack_settings:write'])]
+    public ?string $tokenSecret = null;
+
+    #[Groups(['bookstack_settings:read'])]
+    public bool $hasToken = false;
+}
+```
+
+- [ ] **Step 2: Create BookStackSettingsProvider**
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\State;
+
+use ApiPlatform\Metadata\Operation;
+use ApiPlatform\State\ProviderInterface;
+use App\ApiResource\BookStackSettings;
+use App\Repository\BookStackConfigurationRepository;
+
+final readonly class BookStackSettingsProvider implements ProviderInterface
+{
+    public function __construct(
+        private BookStackConfigurationRepository $configRepository,
+    ) {}
+
+    public function provide(Operation $operation, array $uriVariables = [], array $context = []): BookStackSettings
+    {
+        $config = $this->configRepository->findSingleton();
+        $dto    = new BookStackSettings();
+
+        if (null !== $config) {
+            $dto->url      = $config->getUrl();
+            $dto->hasToken = $config->hasToken();
+        }
+
+        return $dto;
+    }
+}
+```
+
+- [ ] **Step 3: Create BookStackSettingsProcessor**
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\State;
+
+use ApiPlatform\Metadata\Operation;
+use ApiPlatform\State\ProcessorInterface;
+use App\ApiResource\BookStackSettings;
+use App\Entity\BookStackConfiguration;
+use App\Repository\BookStackConfigurationRepository;
+use App\Service\TokenEncryptor;
+use Doctrine\ORM\EntityManagerInterface;
+
+final readonly class BookStackSettingsProcessor implements ProcessorInterface
+{
+    public function __construct(
+        private EntityManagerInterface $em,
+        private BookStackConfigurationRepository $configRepository,
+        private TokenEncryptor $tokenEncryptor,
+    ) {}
+
+    public function process(mixed $data, Operation $operation, array $uriVariables = [], array $context = []): BookStackSettings
+    {
+        assert($data instanceof BookStackSettings);
+
+        $config = $this->configRepository->findSingleton();
+        if (null === $config) {
+            $config = new BookStackConfiguration();
+        }
+
+        $config->setUrl($data->url);
+
+        if (null !== $data->tokenId && '' !== $data->tokenId
+            && null !== $data->tokenSecret && '' !== $data->tokenSecret) {
+            $config->setEncryptedTokenId($this->tokenEncryptor->encrypt($data->tokenId));
+            $config->setEncryptedTokenSecret($this->tokenEncryptor->encrypt($data->tokenSecret));
+        }
+
+        $this->em->persist($config);
+        $this->em->flush();
+
+        $result           = new BookStackSettings();
+        $result->url      = $config->getUrl();
+        $result->hasToken = $config->hasToken();
+
+        return $result;
+    }
+}
+```
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/ApiResource/BookStackSettings.php src/State/BookStackSettingsProvider.php src/State/BookStackSettingsProcessor.php
+git commit -m "feat(bookstack) : add BookStackSettings API resource with provider and processor"
+```
+
+---
+
+### Task 9: BookStackTestConnection API Resource
+
+**Files:**
+- Create: `src/ApiResource/BookStackTestConnection.php`
+- Create: `src/State/BookStackTestConnectionProvider.php`
+
+- [ ] **Step 1: Create BookStackTestConnection DTO**
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\ApiResource;
+
+use ApiPlatform\Metadata\ApiResource;
+use ApiPlatform\Metadata\Post;
+use App\State\BookStackTestConnectionProvider;
+use Symfony\Component\Serializer\Attribute\Groups;
+
+#[ApiResource(
+    operations: [
+        new Post(
+            uriTemplate: '/settings/bookstack/test',
+            input: false,
+            normalizationContext: ['groups' => ['bookstack_test:read']],
+            provider: BookStackTestConnectionProvider::class,
+            processor: BookStackTestConnectionProvider::class,
+            security: "is_granted('ROLE_ADMIN')",
+        ),
+    ],
+)]
+final class BookStackTestConnection
+{
+    #[Groups(['bookstack_test:read'])]
+    public bool $success = false;
+}
+```
+
+- [ ] **Step 2: Create BookStackTestConnectionProvider**
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\State;
+
+use ApiPlatform\Metadata\Operation;
+use ApiPlatform\State\ProcessorInterface;
+use ApiPlatform\State\ProviderInterface;
+use App\ApiResource\BookStackTestConnection;
+use App\Service\BookStackApiService;
+
+final readonly class BookStackTestConnectionProvider implements ProviderInterface, ProcessorInterface
+{
+    public function __construct(
+        private BookStackApiService $bookStackApiService,
+    ) {}
+
+    public function provide(Operation $operation, array $uriVariables = [], array $context = []): BookStackTestConnection
+    {
+        return new BookStackTestConnection();
+    }
+
+    public function process(mixed $data, Operation $operation, array $uriVariables = [], array $context = []): BookStackTestConnection
+    {
+        $result          = new BookStackTestConnection();
+        $result->success = $this->bookStackApiService->testConnection();
+
+        return $result;
+    }
+}
+```
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/ApiResource/BookStackTestConnection.php src/State/BookStackTestConnectionProvider.php
+git commit -m "feat(bookstack) : add BookStackTestConnection API resource"
+```
+
+---
+
+### Task 10: BookStackShelf API Resource
+
+**Files:**
+- Create: `src/ApiResource/BookStackShelf.php`
+- Create: `src/State/BookStackShelfProvider.php`
+
+- [ ] **Step 1: Create BookStackShelf DTO**
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\ApiResource;
+
+use ApiPlatform\Metadata\ApiResource;
+use ApiPlatform\Metadata\GetCollection;
+use App\State\BookStackShelfProvider;
+use Symfony\Component\Serializer\Attribute\Groups;
+
+#[ApiResource(
+    operations: [
+        new GetCollection(
+            uriTemplate: '/bookstack/shelves',
+            normalizationContext: ['groups' => ['bookstack_shelf:read']],
+            provider: BookStackShelfProvider::class,
+            security: "is_granted('ROLE_ADMIN')",
+        ),
+    ],
+)]
+final class BookStackShelf
+{
+    #[Groups(['bookstack_shelf:read'])]
+    public int $id = 0;
+
+    #[Groups(['bookstack_shelf:read'])]
+    public string $name = '';
+}
+```
+
+- [ ] **Step 2: Create BookStackShelfProvider**
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\State;
+
+use ApiPlatform\Metadata\Operation;
+use ApiPlatform\State\ProviderInterface;
+use App\ApiResource\BookStackShelf;
+use App\Exception\BookStackApiException;
+use App\Service\BookStackApiService;
+use Symfony\Component\HttpKernel\Exception\BadRequestHttpException;
+
+final readonly class BookStackShelfProvider implements ProviderInterface
+{
+    public function __construct(
+        private BookStackApiService $bookStackApiService,
+    ) {}
+
+    public function provide(Operation $operation, array $uriVariables = [], array $context = []): array
+    {
+        try {
+            $shelves = $this->bookStackApiService->listShelves();
+        } catch (BookStackApiException $e) {
+            throw new BadRequestHttpException($e->getMessage(), $e);
+        }
+
+        return array_map(static function (array $shelf): BookStackShelf {
+            $dto       = new BookStackShelf();
+            $dto->id   = $shelf['id'] ?? 0;
+            $dto->name = $shelf['name'] ?? '';
+
+            return $dto;
+        }, $shelves);
+    }
+}
+```
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/ApiResource/BookStackShelf.php src/State/BookStackShelfProvider.php
+git commit -m "feat(bookstack) : add BookStackShelf API resource for listing shelves"
+```
+
+---
+
+### Task 11: BookStackLink API Resource (CRUD)
+
+**Files:**
+- Create: `src/ApiResource/BookStackLink.php`
+- Create: `src/State/BookStackLinkProvider.php`
+- Create: `src/State/BookStackLinkProcessor.php`
+
+- [ ] **Step 1: Create BookStackLink DTO**
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\ApiResource;
+
+use ApiPlatform\Metadata\ApiResource;
+use ApiPlatform\Metadata\Delete;
+use ApiPlatform\Metadata\GetCollection;
+use ApiPlatform\Metadata\Post;
+use App\State\BookStackLinkProcessor;
+use App\State\BookStackLinkProvider;
+use Symfony\Component\Serializer\Attribute\Groups;
+
+#[ApiResource(
+    operations: [
+        new GetCollection(
+            uriTemplate: '/tasks/{taskId}/bookstack/links',
+            normalizationContext: ['groups' => ['bookstack_link:read']],
+            provider: BookStackLinkProvider::class,
+            security: "is_granted('IS_AUTHENTICATED_FULLY')",
+        ),
+        new Post(
+            uriTemplate: '/tasks/{taskId}/bookstack/links',
+            denormalizationContext: ['groups' => ['bookstack_link:write']],
+            normalizationContext: ['groups' => ['bookstack_link:read']],
+            provider: BookStackLinkProvider::class,
+            processor: BookStackLinkProcessor::class,
+            security: "is_granted('IS_AUTHENTICATED_FULLY')",
+        ),
+        new Delete(
+            uriTemplate: '/tasks/{taskId}/bookstack/links/{id}',
+            provider: BookStackLinkProvider::class,
+            processor: BookStackLinkProcessor::class,
+            security: "is_granted('IS_AUTHENTICATED_FULLY')",
+        ),
+    ],
+)]
+final class BookStackLink
+{
+    #[Groups(['bookstack_link:read'])]
+    public ?int $id = null;
+
+    #[Groups(['bookstack_link:read', 'bookstack_link:write'])]
+    public int $bookstackId = 0;
+
+    #[Groups(['bookstack_link:read', 'bookstack_link:write'])]
+    public string $bookstackType = '';
+
+    #[Groups(['bookstack_link:read', 'bookstack_link:write'])]
+    public string $title = '';
+
+    #[Groups(['bookstack_link:read', 'bookstack_link:write'])]
+    public string $url = '';
+
+    #[Groups(['bookstack_link:read'])]
+    public ?string $createdAt = null;
+}
+```
+
+- [ ] **Step 2: Create BookStackLinkProvider**
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\State;
+
+use ApiPlatform\Metadata\Delete;
+use ApiPlatform\Metadata\Operation;
+use ApiPlatform\Metadata\Post;
+use ApiPlatform\State\ProviderInterface;
+use App\ApiResource\BookStackLink;
+use App\Repository\TaskBookStackLinkRepository;
+use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
+
+final readonly class BookStackLinkProvider implements ProviderInterface
+{
+    public function __construct(
+        private TaskBookStackLinkRepository $linkRepository,
+    ) {}
+
+    public function provide(Operation $operation, array $uriVariables = [], array $context = []): array|BookStackLink
+    {
+        if ($operation instanceof Post) {
+            return new BookStackLink();
+        }
+
+        if ($operation instanceof Delete) {
+            $link = $this->linkRepository->find($uriVariables['id'] ?? 0);
+            if (null === $link) {
+                throw new NotFoundHttpException('Link not found.');
+            }
+            $dto     = new BookStackLink();
+            $dto->id = $link->getId();
+
+            return $dto;
+        }
+
+        $taskId = $uriVariables['taskId'] ?? 0;
+        $links  = $this->linkRepository->findByTaskId($taskId);
+
+        return array_map(static function (\App\Entity\TaskBookStackLink $link): BookStackLink {
+            $dto                = new BookStackLink();
+            $dto->id            = $link->getId();
+            $dto->bookstackId   = $link->getBookstackId();
+            $dto->bookstackType = $link->getBookstackType();
+            $dto->title         = $link->getTitle();
+            $dto->url           = $link->getUrl();
+            $dto->createdAt     = $link->getCreatedAt()->format('c');
+
+            return $dto;
+        }, $links);
+    }
+}
+```
+
+- [ ] **Step 3: Create BookStackLinkProcessor**
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\State;
+
+use ApiPlatform\Metadata\Delete;
+use ApiPlatform\Metadata\Operation;
+use ApiPlatform\State\ProcessorInterface;
+use App\ApiResource\BookStackLink;
+use App\Entity\Task;
+use App\Entity\TaskBookStackLink;
+use App\Repository\TaskBookStackLinkRepository;
+use Doctrine\ORM\EntityManagerInterface;
+use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
+
+final readonly class BookStackLinkProcessor implements ProcessorInterface
+{
+    public function __construct(
+        private EntityManagerInterface $em,
+        private TaskBookStackLinkRepository $linkRepository,
+    ) {}
+
+    public function process(mixed $data, Operation $operation, array $uriVariables = [], array $context = []): ?BookStackLink
+    {
+        if ($operation instanceof Delete) {
+            return $this->handleDelete($uriVariables);
+        }
+
+        return $this->handleCreate($data, $uriVariables);
+    }
+
+    private function handleCreate(mixed $data, array $uriVariables): BookStackLink
+    {
+        assert($data instanceof BookStackLink);
+
+        $taskId = $uriVariables['taskId'] ?? 0;
+        $task   = $this->em->getRepository(Task::class)->find($taskId);
+
+        if (null === $task) {
+            throw new NotFoundHttpException('Task not found.');
+        }
+
+        $link = new TaskBookStackLink();
+        $link->setTask($task);
+        $link->setBookstackId($data->bookstackId);
+        $link->setBookstackType($data->bookstackType);
+        $link->setTitle($data->title);
+        $link->setUrl($data->url);
+
+        $this->em->persist($link);
+        $this->em->flush();
+
+        $result                = new BookStackLink();
+        $result->id            = $link->getId();
+        $result->bookstackId   = $link->getBookstackId();
+        $result->bookstackType = $link->getBookstackType();
+        $result->title         = $link->getTitle();
+        $result->url           = $link->getUrl();
+        $result->createdAt     = $link->getCreatedAt()->format('c');
+
+        return $result;
+    }
+
+    private function handleDelete(array $uriVariables): null
+    {
+        $linkId = $uriVariables['id'] ?? 0;
+        $link   = $this->linkRepository->find($linkId);
+
+        if (null === $link) {
+            throw new NotFoundHttpException('Link not found.');
+        }
+
+        $this->em->remove($link);
+        $this->em->flush();
+
+        return null;
+    }
+}
+```
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/ApiResource/BookStackLink.php src/State/BookStackLinkProvider.php src/State/BookStackLinkProcessor.php
+git commit -m "feat(bookstack) : add BookStackLink API resource with CRUD operations"
+```
+
+---
+
+### Task 12: BookStackSearchResult API Resource
+
+**Files:**
+- Create: `src/ApiResource/BookStackSearchResult.php`
+- Create: `src/State/BookStackSearchResultProvider.php`
+
+- [ ] **Step 1: Create BookStackSearchResult DTO**
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\ApiResource;
+
+use ApiPlatform\Metadata\ApiResource;
+use ApiPlatform\Metadata\GetCollection;
+use App\State\BookStackSearchResultProvider;
+use Symfony\Component\Serializer\Attribute\Groups;
+
+#[ApiResource(
+    operations: [
+        new GetCollection(
+            uriTemplate: '/tasks/{taskId}/bookstack/search',
+            normalizationContext: ['groups' => ['bookstack_search:read']],
+            provider: BookStackSearchResultProvider::class,
+            security: "is_granted('IS_AUTHENTICATED_FULLY')",
+        ),
+    ],
+)]
+final class BookStackSearchResult
+{
+    #[Groups(['bookstack_search:read'])]
+    public int $id = 0;
+
+    #[Groups(['bookstack_search:read'])]
+    public string $type = '';
+
+    #[Groups(['bookstack_search:read'])]
+    public string $name = '';
+
+    #[Groups(['bookstack_search:read'])]
+    public string $url = '';
+}
+```
+
+- [ ] **Step 2: Create BookStackSearchResultProvider**
+
+The provider reads the `q` query parameter from the request, resolves the task's project shelf, and calls the API service.
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\State;
+
+use ApiPlatform\Metadata\Operation;
+use ApiPlatform\State\ProviderInterface;
+use App\ApiResource\BookStackSearchResult;
+use App\Entity\Task;
+use App\Exception\BookStackApiException;
+use App\Service\BookStackApiService;
+use Doctrine\ORM\EntityManagerInterface;
+use Symfony\Component\HttpFoundation\RequestStack;
+use Symfony\Component\HttpKernel\Exception\BadRequestHttpException;
+
+final readonly class BookStackSearchResultProvider implements ProviderInterface
+{
+    public function __construct(
+        private BookStackApiService $bookStackApiService,
+        private EntityManagerInterface $em,
+        private RequestStack $requestStack,
+    ) {}
+
+    public function provide(Operation $operation, array $uriVariables = [], array $context = []): array
+    {
+        $taskId = $uriVariables['taskId'] ?? 0;
+        $task   = $this->em->getRepository(Task::class)->find($taskId);
+
+        if (null === $task || null === $task->getProject()) {
+            return [];
+        }
+
+        $shelfId = $task->getProject()->getBookstackShelfId();
+        if (null === $shelfId) {
+            return [];
+        }
+
+        $request = $this->requestStack->getCurrentRequest();
+        $query   = $request?->query->get('q', '') ?? '';
+
+        if ('' === trim($query)) {
+            return [];
+        }
+
+        try {
+            $results = $this->bookStackApiService->searchInShelf($shelfId, $query);
+        } catch (BookStackApiException $e) {
+            throw new BadRequestHttpException($e->getMessage(), $e);
+        }
+
+        return array_map(static function (array $item): BookStackSearchResult {
+            $dto       = new BookStackSearchResult();
+            $dto->id   = $item['id'];
+            $dto->type = $item['type'];
+            $dto->name = $item['name'];
+            $dto->url  = $item['url'];
+
+            return $dto;
+        }, $results);
+    }
+}
+```
+
+- [ ] **Step 3: Verify cache clear passes**
+
+Run: `make cache-clear`
+Expected: No errors.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/ApiResource/BookStackSearchResult.php src/State/BookStackSearchResultProvider.php
+git commit -m "feat(bookstack) : add BookStackSearchResult API resource for shelf-scoped search"
+```
+
+---
+
+## Chunk 3: Frontend — Service, DTOs, Admin Tab
+
+### Task 13: Frontend DTOs
+
+**Files:**
+- Create: `frontend/services/dto/bookstack.ts`
+
+- [ ] **Step 1: Create BookStack DTOs**
+
+```typescript
+export type BookStackSettings = {
+    url: string | null
+    hasToken: boolean
+}
+
+export type BookStackSettingsWrite = {
+    url: string | null
+    tokenId: string | null
+    tokenSecret: string | null
+}
+
+export type BookStackTestResult = {
+    success: boolean
+}
+
+export type BookStackShelf = {
+    id: number
+    name: string
+}
+
+export type BookStackLink = {
+    id: number
+    bookstackId: number
+    bookstackType: 'page' | 'book'
+    title: string
+    url: string
+    createdAt: string
+}
+
+export type BookStackLinkCreate = {
+    bookstackId: number
+    bookstackType: 'page' | 'book'
+    title: string
+    url: string
+}
+
+export type BookStackSearchResult = {
+    id: number
+    type: 'page' | 'book'
+    name: string
+    url: string
+}
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add frontend/services/dto/bookstack.ts
+git commit -m "feat(bookstack) : add frontend BookStack DTOs"
+```
+
+---
+
+### Task 14: Frontend BookStack Service
+
+**Files:**
+- Create: `frontend/services/bookstack.ts`
+
+- [ ] **Step 1: Create the service**
+
+```typescript
+import type {
+    BookStackSettings,
+    BookStackSettingsWrite,
+    BookStackTestResult,
+    BookStackShelf,
+    BookStackLink,
+    BookStackLinkCreate,
+    BookStackSearchResult,
+} from './dto/bookstack'
+import type { HydraCollection } from '~/utils/api'
+import { extractHydraMembers } from '~/utils/api'
+
+export function useBookStackService() {
+    const api = useApi()
+
+    async function getSettings(): Promise<BookStackSettings> {
+        return api.get<BookStackSettings>('/settings/bookstack')
+    }
+
+    async function saveSettings(payload: BookStackSettingsWrite): Promise<BookStackSettings> {
+        return api.put<BookStackSettings>('/settings/bookstack', payload as Record<string, unknown>, {
+            toastSuccessKey: 'bookstack.settings.saved',
+        })
+    }
+
+    async function testConnection(): Promise<BookStackTestResult> {
+        return api.post<BookStackTestResult>('/settings/bookstack/test')
+    }
+
+    async function listShelves(): Promise<BookStackShelf[]> {
+        const data = await api.get<HydraCollection<BookStackShelf>>('/bookstack/shelves')
+        return extractHydraMembers(data)
+    }
+
+    async function getLinks(taskId: number): Promise<BookStackLink[]> {
+        const data = await api.get<HydraCollection<BookStackLink>>(`/tasks/${taskId}/bookstack/links`)
+        return extractHydraMembers(data)
+    }
+
+    async function addLink(taskId: number, payload: BookStackLinkCreate): Promise<BookStackLink> {
+        return api.post<BookStackLink>(`/tasks/${taskId}/bookstack/links`, payload as Record<string, unknown>)
+    }
+
+    async function removeLink(taskId: number, linkId: number): Promise<void> {
+        await api.delete(`/tasks/${taskId}/bookstack/links/${linkId}`)
+    }
+
+    async function search(taskId: number, query: string): Promise<BookStackSearchResult[]> {
+        const data = await api.get<HydraCollection<BookStackSearchResult>>(
+            `/tasks/${taskId}/bookstack/search`,
+            { q: query },
+        )
+        return extractHydraMembers(data)
+    }
+
+    return {
+        getSettings,
+        saveSettings,
+        testConnection,
+        listShelves,
+        getLinks,
+        addLink,
+        removeLink,
+        search,
+    }
+}
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add frontend/services/bookstack.ts
+git commit -m "feat(bookstack) : add frontend BookStack service"
+```
+
+---
+
+### Task 15: i18n Translations
+
+**Files:**
+- Modify: `frontend/i18n/locales/fr.json`
+
+- [ ] **Step 1: Add BookStack translations**
+
+Add the following block inside the root JSON object (after the `"gitea"` block):
+
+```json
+    "bookstack": {
+        "settings": {
+            "title": "Configuration BookStack",
+            "url": "URL du serveur",
+            "urlPlaceholder": "https://wiki.example.com",
+            "tokenId": "Token ID",
+            "tokenIdPlaceholder": "Entrez le Token ID",
+            "tokenSecret": "Token Secret",
+            "tokenSecretPlaceholder": "Entrez le Token Secret",
+            "tokenConfigured": "Token configuré",
+            "save": "Enregistrer",
+            "saved": "Configuration BookStack sauvegardée.",
+            "testConnection": "Tester la connexion",
+            "testSuccess": "Connexion réussie.",
+            "testFailed": "Connexion échouée."
+        },
+        "links": {
+            "title": "Documentation",
+            "searchPlaceholder": "Rechercher une page ou un livre...",
+            "noResults": "Aucun résultat",
+            "empty": "Aucun document lié"
+        }
+    }
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add frontend/i18n/locales/fr.json
+git commit -m "feat(bookstack) : add i18n translations for BookStack"
+```
+
+---
+
+### Task 16: AdminBookStackTab Component
+
+**Files:**
+- Create: `frontend/components/admin/AdminBookStackTab.vue`
+
+- [ ] **Step 1: Create the admin tab component**
+
+```vue
+<template>
+    <div>
+        <h2 class="text-lg font-bold text-neutral-900">{{ $t('bookstack.settings.title') }}</h2>
+
+        <form class="mt-6 max-w-lg space-y-4" @submit.prevent="handleSave">
+            <MalioInputText
+                v-model="form.url"
+                :label="$t('bookstack.settings.url')"
+                :placeholder="$t('bookstack.settings.urlPlaceholder')"
+                input-class="w-full"
+            />
+
+            <div>
+                <MalioInputText
+                    v-model="form.tokenId"
+                    :label="$t('bookstack.settings.tokenId')"
+                    :placeholder="$t('bookstack.settings.tokenIdPlaceholder')"
+                    input-class="w-full"
+                    type="password"
+                />
+            </div>
+
+            <div>
+                <MalioInputText
+                    v-model="form.tokenSecret"
+                    :label="$t('bookstack.settings.tokenSecret')"
+                    :placeholder="$t('bookstack.settings.tokenSecretPlaceholder')"
+                    input-class="w-full"
+                    type="password"
+                />
+                <p v-if="hasToken && !form.tokenId && !form.tokenSecret" class="mt-1 text-xs text-green-600">
+                    {{ $t('bookstack.settings.tokenConfigured') }}
+                </p>
+            </div>
+
+            <div class="flex gap-3">
+                <button
+                    type="submit"
+                    class="rounded-md bg-primary-500 px-4 py-2 text-sm font-semibold text-white hover:bg-secondary-500 disabled:opacity-50"
+                    :disabled="isSaving"
+                >
+                    {{ $t('bookstack.settings.save') }}
+                </button>
+                <button
+                    type="button"
+                    class="rounded-md border border-neutral-300 px-4 py-2 text-sm font-semibold text-neutral-700 hover:bg-neutral-50 disabled:opacity-50"
+                    :disabled="isTesting"
+                    @click="handleTest"
+                >
+                    {{ $t('bookstack.settings.testConnection') }}
+                </button>
+            </div>
+
+            <p v-if="testResult !== null" class="text-sm font-medium" :class="testResult ? 'text-green-600' : 'text-red-600'">
+                {{ testResult ? $t('bookstack.settings.testSuccess') : $t('bookstack.settings.testFailed') }}
+            </p>
+        </form>
+    </div>
+</template>
+
+<script setup lang="ts">
+import { useBookStackService } from '~/services/bookstack'
+
+const { getSettings, saveSettings, testConnection } = useBookStackService()
+
+const form = reactive({
+    url: '',
+    tokenId: '',
+    tokenSecret: '',
+})
+
+const hasToken = ref(false)
+const isSaving = ref(false)
+const isTesting = ref(false)
+const testResult = ref<boolean | null>(null)
+
+async function loadSettings() {
+    const settings = await getSettings()
+    form.url = settings.url ?? ''
+    hasToken.value = settings.hasToken
+}
+
+async function handleSave() {
+    isSaving.value = true
+    try {
+        const result = await saveSettings({
+            url: form.url.trim() || null,
+            tokenId: form.tokenId || null,
+            tokenSecret: form.tokenSecret || null,
+        })
+        hasToken.value = result.hasToken
+        form.tokenId = ''
+        form.tokenSecret = ''
+        testResult.value = null
+    } finally {
+        isSaving.value = false
+    }
+}
+
+async function handleTest() {
+    isTesting.value = true
+    testResult.value = null
+    try {
+        const result = await testConnection()
+        testResult.value = result.success
+    } catch {
+        testResult.value = false
+    } finally {
+        isTesting.value = false
+    }
+}
+
+onMounted(() => {
+    loadSettings()
+})
+</script>
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add frontend/components/admin/AdminBookStackTab.vue
+git commit -m "feat(bookstack) : add AdminBookStackTab component"
+```
+
+---
+
+### Task 17: Add BookStack Tab to Admin Page
+
+**Files:**
+- Modify: `frontend/pages/admin.vue`
+
+- [ ] **Step 1: Add the BookStack tab**
+
+In `frontend/pages/admin.vue`:
+
+1. In the `tabs` array, add after the gitea entry:
+
+```typescript
+    { key: 'bookstack', label: 'BookStack' },
+```
+
+2. In the `type TabKey` union, the new key is automatically included since it's derived from `typeof tabs[number]['key']`.
+
+3. In the template, add after `<AdminGiteaTab v-if="activeTab === 'gitea'" />`:
+
+```html
+            <AdminBookStackTab v-if="activeTab === 'bookstack'" />
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add frontend/pages/admin.vue
+git commit -m "feat(bookstack) : add BookStack tab to admin page"
+```
+
+---
+
+## Chunk 4: Frontend — Project Drawer, Task Component, Task Modal
+
+### Task 18: Update ProjectDrawer with Shelf Select
+
+**Files:**
+- Modify: `frontend/components/project/ProjectDrawer.vue`
+- Modify: `frontend/services/dto/project.ts`
+
+- [ ] **Step 1: Update Project DTOs**
+
+In `frontend/services/dto/project.ts`:
+
+Add to `Project` type:
+
+```typescript
+    bookstackShelfId: number | null
+    bookstackShelfName: string | null
+```
+
+Add to `ProjectWrite` type:
+
+```typescript
+    bookstackShelfId?: number | null
+    bookstackShelfName?: string | null
+```
+
+- [ ] **Step 2: Update ProjectDrawer script**
+
+In `frontend/components/project/ProjectDrawer.vue`:
+
+1. Add import at the top of the script:
+
+```typescript
+import type { BookStackShelf } from '~/services/dto/bookstack'
+import { useBookStackService } from '~/services/bookstack'
+```
+
+2. After the Gitea service setup (around line 93-97), add:
+
+```typescript
+const { listShelves } = useBookStackService()
+const bookstackShelves = ref<BookStackShelf[]>([])
+
+const bookstackShelfOptions = computed(() =>
+    bookstackShelves.value.map(s => ({ label: s.name, value: s.id }))
+)
+```
+
+3. Add `bookstackShelfId` to the `form` reactive object:
+
+```typescript
+    bookstackShelfId: null as number | null,
+```
+
+4. In the `watch` that populates the form when the drawer opens, add (in the `if (props.project)` branch):
+
+```typescript
+            form.bookstackShelfId = props.project.bookstackShelfId ?? null
+```
+
+And in the `else` branch:
+
+```typescript
+            form.bookstackShelfId = null
+```
+
+5. In `handleSubmit`, after the Gitea payload block (after `payload.giteaRepo = null`), add:
+
+```typescript
+        if (form.bookstackShelfId) {
+            const shelf = bookstackShelves.value.find(s => s.id === form.bookstackShelfId)
+            payload.bookstackShelfId = form.bookstackShelfId
+            payload.bookstackShelfName = shelf?.name ?? null
+        } else {
+            payload.bookstackShelfId = null
+            payload.bookstackShelfName = null
+        }
+```
+
+6. In `onMounted`, after the Gitea repos loading, add:
+
+```typescript
+    try {
+        bookstackShelves.value = await listShelves()
+    } catch {
+        // BookStack not configured, ignore
+    }
+```
+
+- [ ] **Step 3: Update ProjectDrawer template**
+
+After the Gitea repo select `<div>` (around line 35-43), add:
+
+```html
+            <div v-if="bookstackShelves.length" class="mt-4">
+                <MalioSelect
+                    v-model="form.bookstackShelfId"
+                    :options="bookstackShelfOptions"
+                    label="Étagère BookStack"
+                    empty-option-label="Aucune étagère"
+                    min-width="w-full"
+                />
+            </div>
+```
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add frontend/services/dto/project.ts frontend/components/project/ProjectDrawer.vue
+git commit -m "feat(bookstack) : add shelf select to ProjectDrawer"
+```
+
+---
+
+### Task 19: TaskBookStackLinks Component
+
+**Files:**
+- Create: `frontend/components/task/TaskBookStackLinks.vue`
+
+- [ ] **Step 1: Create the component**
+
+```vue
+<template>
+    <div class="mt-5">
+        <p class="mb-2 text-sm font-medium text-neutral-700">{{ $t('bookstack.links.title') }}</p>
+
+        <!-- Search -->
+        <div class="relative">
+            <MalioInputText
+                v-model="searchQuery"
+                :placeholder="$t('bookstack.links.searchPlaceholder')"
+                input-class="w-full"
+            />
+
+            <!-- Dropdown results -->
+            <div
+                v-if="searchResults.length > 0"
+                class="absolute z-30 mt-1 w-full rounded-md border border-neutral-200 bg-white shadow-lg"
+            >
+                <button
+                    v-for="result in searchResults"
+                    :key="`${result.type}-${result.id}`"
+                    type="button"
+                    class="flex w-full items-center gap-2 px-3 py-2 text-left text-sm hover:bg-neutral-50"
+                    @click="handleAdd(result)"
+                >
+                    <Icon
+                        :name="result.type === 'page' ? 'mdi:file-document-outline' : 'mdi:book-outline'"
+                        size="16"
+                        class="shrink-0 text-neutral-400"
+                    />
+                    <span class="truncate">{{ result.name }}</span>
+                    <span class="ml-auto shrink-0 text-xs text-neutral-400">{{ result.type }}</span>
+                </button>
+            </div>
+
+            <p v-if="searchQuery.length >= 2 && !isSearching && searchResults.length === 0 && hasSearched" class="mt-1 text-xs text-neutral-400">
+                {{ $t('bookstack.links.noResults') }}
+            </p>
+        </div>
+
+        <!-- Linked documents -->
+        <div v-if="links.length > 0" class="mt-3 space-y-1">
+            <div
+                v-for="link in links"
+                :key="link.id"
+                class="flex items-center gap-2 rounded-md px-2 py-1.5 text-sm hover:bg-neutral-50"
+            >
+                <Icon
+                    :name="link.bookstackType === 'page' ? 'mdi:file-document-outline' : 'mdi:book-outline'"
+                    size="16"
+                    class="shrink-0 text-neutral-400"
+                />
+                <a
+                    :href="link.url"
+                    target="_blank"
+                    rel="noopener noreferrer"
+                    class="truncate text-primary-500 hover:underline"
+                >
+                    {{ link.title }}
+                </a>
+                <button
+                    type="button"
+                    class="ml-auto shrink-0 text-neutral-300 hover:text-red-500"
+                    @click="handleRemove(link.id)"
+                >
+                    <Icon name="mdi:close" size="16" />
+                </button>
+            </div>
+        </div>
+
+        <p v-else-if="!isLoading" class="mt-2 text-xs text-neutral-400">
+            {{ $t('bookstack.links.empty') }}
+        </p>
+    </div>
+</template>
+
+<script setup lang="ts">
+import type { BookStackLink, BookStackSearchResult } from '~/services/dto/bookstack'
+import { useBookStackService } from '~/services/bookstack'
+
+const props = defineProps<{
+    taskId: number
+}>()
+
+const { getLinks, addLink, removeLink, search } = useBookStackService()
+
+const links = ref<BookStackLink[]>([])
+const searchQuery = ref('')
+const searchResults = ref<BookStackSearchResult[]>([])
+const isLoading = ref(true)
+const isSearching = ref(false)
+const hasSearched = ref(false)
+
+let debounceTimer: ReturnType<typeof setTimeout> | null = null
+
+watch(searchQuery, (query) => {
+    if (debounceTimer) clearTimeout(debounceTimer)
+    hasSearched.value = false
+    searchResults.value = []
+
+    if (query.trim().length < 2) {
+        return
+    }
+
+    debounceTimer = setTimeout(async () => {
+        isSearching.value = true
+        try {
+            searchResults.value = await search(props.taskId, query.trim())
+        } catch {
+            searchResults.value = []
+        } finally {
+            isSearching.value = false
+            hasSearched.value = true
+        }
+    }, 300)
+})
+
+async function handleAdd(result: BookStackSearchResult) {
+    searchQuery.value = ''
+    searchResults.value = []
+    hasSearched.value = false
+
+    // Check if already linked
+    if (links.value.some(l => l.bookstackId === result.id && l.bookstackType === result.type)) {
+        return
+    }
+
+    try {
+        const created = await addLink(props.taskId, {
+            bookstackId: result.id,
+            bookstackType: result.type,
+            title: result.name,
+            url: result.url,
+        })
+        links.value.unshift(created)
+    } catch {
+        // Error handled by useApi toast
+    }
+}
+
+async function handleRemove(linkId: number) {
+    try {
+        await removeLink(props.taskId, linkId)
+        links.value = links.value.filter(l => l.id !== linkId)
+    } catch {
+        // Error handled by useApi toast
+    }
+}
+
+onMounted(async () => {
+    try {
+        links.value = await getLinks(props.taskId)
+    } catch {
+        // Error handled by useApi toast
+    } finally {
+        isLoading.value = false
+    }
+})
+</script>
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add frontend/components/task/TaskBookStackLinks.vue
+git commit -m "feat(bookstack) : add TaskBookStackLinks component"
+```
+
+---
+
+### Task 20: Integrate into TaskModal
+
+**Files:**
+- Modify: `frontend/components/task/TaskModal.vue`
+
+- [ ] **Step 1: Add BookStack section to TaskModal template**
+
+In `frontend/components/task/TaskModal.vue`, after the `TaskGitSection` block (around line 82-84):
+
+```html
+                        <!-- BookStack links -->
+                        <TaskBookStackLinks
+                            v-if="hasBookStack && isEditing && task"
+                            :task-id="task.id"
+                        />
+```
+
+- [ ] **Step 2: Add hasBookStack computed**
+
+In the `<script setup>` section, after the `hasGitea` computed (around line 136):
+
+```typescript
+const hasBookStack = computed(() => {
+    return !!props.task?.project?.bookstackShelfId
+})
+```
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add frontend/components/task/TaskModal.vue
+git commit -m "feat(bookstack) : integrate TaskBookStackLinks into TaskModal"
+```
+
+---
+
+## Chunk 5: Verification
+
+### Task 21: End-to-End Verification
+
+- [ ] **Step 1: Clear cache and verify backend**
+
+```bash
+make cache-clear
+```
+
+Expected: No errors.
+
+- [ ] **Step 2: Run PHP CS Fixer**
+
+```bash
+make php-cs-fixer-allow-risky
+```
+
+Fix any code style issues if found.
+
+- [ ] **Step 3: Build Nuxt**
+
+```bash
+cd frontend && npx nuxi build
+```
+
+Expected: Build succeeds with no TypeScript errors.
+
+- [ ] **Step 4: Run PHPUnit tests**
+
+```bash
+make test
+```
+
+Expected: All existing tests pass.
+
+- [ ] **Step 5: Fix any issues found and commit**
+
+```bash
+git add -A
+git commit -m "fix(bookstack) : address code style and build issues"
+```
+
+(Only if fixes are needed.)
diff --git a/docs/superpowers/specs/2026-03-15-bookstack-connector-design.md b/docs/superpowers/specs/2026-03-15-bookstack-connector-design.md
index b59b94b..9aeed0e 100644
--- a/docs/superpowers/specs/2026-03-15-bookstack-connector-design.md
+++ b/docs/superpowers/specs/2026-03-15-bookstack-connector-design.md
@@ -294,9 +294,10 @@ src/Service/TokenEncryptor.php  (renommage GITEA_ENCRYPTION_KEY → ENCRYPTION_K
 
 ```
 .env  (renommage GITEA_ENCRYPTION_KEY → ENCRYPTION_KEY)
-docker/.env.docker  (idem)
 ```
 
+> Note : `docker/.env.docker` ne contient pas `GITEA_ENCRYPTION_KEY`. Les développeurs utilisant `docker/.env.docker.local` doivent le mettre à jour manuellement.
+
 ### Frontend — Nouveaux fichiers
 
 ```