> For the complete documentation index, see [llms.txt](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/phases/phase_19/session_02_documents_gallery_write.md).

# Session 02: Documents Gallery (Write: Delete/Restore/Purge)

**Session ID**: `phase19-session02-documents-gallery-write` **Status**: Not Started **Estimated Tasks**: \~18-24 **Estimated Duration**: 3-4 hours

***

## Objective

Add the Documents Gallery tab as a modular read/write surface: list and preview Hermes artifacts through the read bridge, and route delete/restore/purge through admin-gated, path-confined write endpoints. Source-code anchors are `V23/src/components/hermes-documents-gallery.tsx` and the V23 document handlers listed below.

***

## Scope

### In Scope (MVP)

* Source: `V23/src/components/hermes-documents-gallery.tsx` (2,158 lines); writes delete `:428`, restore `:459`/`:1094`, purge `:1118`/`:1141`. Artifact gallery over `~/Documents/Hermes/`, with v2.3 5s polling.
* Target: new `AIOS/src/components/hermes/hermes-documents-gallery.tsx`, added as a `Documents` tab via `hermes-read-only-page.tsx` (TabsList `:150`, TabsContent `:177-189`).
* **Reads:** `GET /__hermes_documents`, `/__hermes_documents/file`, and `/__hermes_documents/trash` from V23 `vite.config.ts:2832`, `:2843`, and `:3009`, through the Phase 16 hook layer.
* **Writes (admin-gated, landed in Phase 16 Session 02), Write Inventory #13-15:**
  * \#13 Document soft-delete -- V23 `vite.config.ts:2914`, client gallery `:428` -- FS move->trash, name confined, reversible.
  * \#14 Document restore -- V23 `vite.config.ts:2952`, client gallery `:459,1094` -- FS move, trashId confined.
  * \#15 Document purge -- V23 `vite.config.ts:3049`, client gallery `:1118,1141` -- permanent FS delete, trashId confined, confirm.
* Poll via the hook layer (React Query refetch interval), not raw `setInterval`.
* Consume the already-copied `AIOS/src/assets/hermes-art/file-types/*.webp` set for pdf/html/markdown/text/data/video/audio/archive/code/other file-type cards.
* Resolve Open Question 3: whether the documents root stays fixed at `~/Documents/Hermes/` for v1 or becomes setup/config-driven. Whichever path is chosen must be path-confined.
* Write affordances disabled with an "admin mode required" hint without the token.

### Out of Scope

* Mission Control (Session 01).
* Long-tail stats, sessions, roles, activity, CLI, and final cleanup (Phase 20).
* Server endpoint implementation (landed Phase 16 Session 02).

***

## Prerequisites

* [ ] Phase 16 complete: documents read/file/trash endpoints and delete/restore/ purge writes registered with security tests; hook query/mutations present.
* [ ] Phase 19 Session 01 complete or independently mergeable; shell and prior tabs from Phases 17-18 in place.
* [ ] Documents root decision recorded before destructive writes ship.

***

## Deliverables

1. A modular Documents Gallery tab rendering artifact list, preview, and trash states through the hook layer.
2. Delete, restore, and purge wired through `useHermesAdmin`, with soft-delete first, confirm on purge, and path confinement for `name`/`trashId`.
3. React Query polling/refetch behavior replacing v2.3 raw polling.
4. Mode-matrix coverage and a `hermes-sections.test.tsx` extension.

***

## Success Criteria

* [ ] Documents Gallery lists, previews, and renders trash state at v2.3 parity.
* [ ] Delete moves to trash and is reversible; restore and purge are admin-gated and path-confined; purge requires confirmation.
* [ ] No raw `setInterval` or raw fetch bypasses the hook layer.
* [ ] File-type art cards render from the copied `.webp` assets.
* [ ] Mode matrix renders; typecheck, lint, and tests pass.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/phases/phase_19/session_02_documents_gallery_write.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.