fix: close search API review findings

docs/ARCHITECTURE.md

@@ -113,6 +113,10 @@ proxy networks.
 Membership, rule, and reindex writes create versioned, durable jobs. The worker updates SQLite
 provenance, exports the membership map, and forces affected paths through the engine. Document listing
 derives effective membership from SQLite and includes direct and rule provenance.
+An unfiltered reindex always includes the document root, even when rule reconciliation also changed
+individual paths. Observing an earlier duplicate forces both the new and former canonical paths
+through Recoll so only the canonical copy carries collection tags. Resubmitting a persistent rule in
+best-effort mode retains prior members under discovery-error paths, as normal reconciliation does.
 
 Search passes all requested collection IDs into one engine query, then verifies hit paths and effective
 membership in SQLite before returning them. Full-text and original-file routes resolve a live canonical
@@ -139,6 +143,8 @@ select returned fields; only `document_id` is unconditional, and inline full tex
 route, cookie, redirect, OpenAPI URL and generated link supports a configured mount prefix. Forwarded
 prefix and origin data are used only from trusted proxies. The exact endpoints and error codes are the
 contract in `docs/specs/001-search-engine-api.md`.
+The built-in OpenAPI JSON and documentation pages also require a valid session, including the Swagger
+OAuth redirect route; prefix middleware applies that guard after normalizing the mount path.
 
 ## Verified Recoll mechanics
 
@@ -184,8 +190,7 @@ Closed by the 001 brainstorm (2026-09-18) — see `docs/DECISIONS.md` for the re
    text is bounded, and full text and file download are separate endpoints.
 
 The remaining 001 design questions — component boundaries, schema, HTTP surface, pagination, error
-semantics and test strategy — are closed in `docs/specs/001-search-engine-api.md`. That spec remains
-draft until maintainer sign-off.
+semantics and test strategy — are closed in the approved `docs/specs/001-search-engine-api.md`.
 
 ## External dependencies
 
@@ -216,4 +221,4 @@ for that spec.
 
 ## Known rough edges
 
-None yet — nothing has been built. Cross-linked backlog: `docs/TODO.md`.
+See the deferred investigations and known issues in `docs/TODO.md`.

docs/DECISIONS.md

@@ -3,6 +3,19 @@
 Append-only, newest first. Never edit or delete an entry — supersede it with a new one that links back.
 One entry per decision a future maintainer would otherwise have to reverse-engineer.
 
+## 2026-09-28 — Guard generated API documentation with the service session
+**Status:** accepted
+**Context:** FastAPI exposes generated OpenAPI and documentation routes outside ordinary route
+dependencies. The accepted spec requires authentication for every route except health and login while
+also requiring OpenAPI to work under a configured mount prefix.
+**Decision:** enforce the existing session check on the generated routes in prefix middleware after
+path normalization. Keep OpenAPI and the documentation pages available to logged-in clients.
+**Alternatives:** leave documentation public (violates R24); disable it (violates the intended OpenAPI
+surface under R29); add a separate authentication mechanism for documentation (unnecessary state).
+**Consequences:** generated documentation shares the API's cookie authentication and URL prefix.
+
+---
+
 ## 2026-09-27 — Persist replay paths and pin original downloads
 **Status:** accepted
 **Context:** Review found that a job could mutate rule or collection state before its indexing step

docs/TODO.md

@@ -5,7 +5,7 @@ Small, specific, independently actionable. Remove only when actually done.
 
 ## Resume here
 
-Last touched 2026-09-27. Spec 001 implementation is in review closure.
+Last touched 2026-09-28. Spec 001 implementation has completed its review fixes and acceptance matrix.
 
 Where the workflow stands (`AGENTS.md` -> Workflow: brainstorm -> spec -> plan -> TDD -> review):
 
@@ -19,19 +19,20 @@ Where the workflow stands (`AGENTS.md` -> Workflow: brainstorm -> spec -> plan -
   identity, additive membership, durable jobs, the atomic membership map, the engine boundary,
   session authentication, the HTTP shell, membership/rule/job routes, scoped search and document
   retrieval, Docker packaging and acceptance coverage. Their checkboxes are current in the plan.
-  The first code review found replay, reconciliation, and download races. A fix checkpoint is on
-  `feat/001-document-discovery`; final verification and branch handoff remain.
+  The first code review found replay, reconciliation, and download races. A follow-up review found
+  generated documentation exposed without a session, incomplete unfiltered reindexing, stale tags
+  after an earlier duplicate became canonical, and lost membership on best-effort rule resubmission.
+  These are fixed on `feat/001-document-discovery`; branch handoff remains.
 
-The next action is Task 14 Step 6: run the full verification matrix, request a follow-up review of the
-fixes, then hand off the branch. Do not repeat Tasks 1–14. The review fixes include idempotent rule
-creation, persisted replay paths, atomic collection cleanup enqueue, unreadable-file preservation,
-departed-path reindexing, directory-rule pagination, recovery request validation, and descriptor-pinned
-downloads. The generated real-container lifecycle test covers these flows through Compose. Its 9-test
-contract/integration suite passed with `RECOLL_MODERN_REQUIRE_DOCKER=1` on 2026-09-27; the host suite
-passed with 157 passed and 4 skipped, and lint/type checking passed. The complete final matrix and
-follow-up review still need to run before completion. Docker Compose may be running on
-port 9124 with `RECOLL_MODERN_DOCUMENTS=/tmp/recoll-modern-corpus`; preserve its named volumes and
-document data. Use `docker compose down` without `-v` when done.
+The next action is branch integration by the maintainer's choice. Do not repeat Tasks 1–14. The review
+fixes include idempotent rule creation, persisted replay paths, atomic collection cleanup enqueue,
+unreadable-file preservation, departed-path reindexing, directory-rule pagination, recovery request
+validation, descriptor-pinned downloads, authenticated API documentation, complete unfiltered
+reindexing, canonical-path retagging, and best-effort rule resubmission. The generated real-container
+lifecycle test covers the major flows through Compose. On 2026-09-28, the host suite passed with 160
+passed and 8 container-dependent skips, and the required-container suite passed all 9 checks. Lint,
+typecheck and build passed. The isolated acceptance Compose project was stopped with
+`docker compose down` and its named volumes were preserved.
 
 Things a resuming agent will otherwise get wrong:
 

docs/plans/001-search-engine-api.md

@@ -1032,6 +1032,6 @@ git add AGENTS.md README.md pyproject.toml uv.lock src tests helper docker Docke
 git commit -m "test: verify search engine API acceptance"
 ```
 
-- [ ] **Step 6: Request review before integration**
+- [x] **Step 6: Request review before integration**
 
 Invoke `superpowers:requesting-code-review`, resolve findings with `superpowers:receiving-code-review`, rerun the complete verification matrix, then use `superpowers:finishing-a-development-branch`. Do not merge, push, or use GitHub tooling; this repository uses Gitea and integration is the maintainer's decision.