> 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/prd_phase_19.md). # PRD Phase 19: Hermes Orchestration And Documents **Status**: Complete **Sessions**: 2 (initial estimate) **Estimated Duration**: 3-5 days **Source Code Roots**: `V23/` = `/home/aiwithapex/projects/claudeos/claude-os-v2.3/`; `AIOS/` = `/home/aiwithapex/projects/aios/`. **Progress**: 2/2 sessions (100%) *** ## Overview Phase 19 adds the two heaviest write surfaces: Mission Control (create / optimize / tick / clear) and the Documents Gallery (delete / restore / purge). Both are full write/orchestration features (per operator direction, Mission Control is not read-only telemetry). All mutations are admin-gated and satisfy the Write-Path Safety Contract. Phase 19 is complete and archived as of 2026-06-02. **Master reference:** the Phase 16 PRD (`.spec_system/PRD/phase_16/PRD_phase_16.md`) holds the legend, component inventory, Write-Path Safety Contract, Complete Write Operation Inventory, security model, assets, validation strategy, and completion criteria. **Code reference roots:** `V23/` = `/home/aiwithapex/projects/claudeos/claude-os-v2.3/`; `AIOS/` = `/home/aiwithapex/projects/aios/`. *** ## Progress Tracker | Session | Name | Status | Est. Tasks | Validated | | ------- | --------------------------------------------------- | -------- | ---------- | ---------- | | 01 | Mission Control (Write: Create/Optimize/Tick/Clear) | Complete | \~18-24 | 2026-06-02 | | 02 | Documents Gallery (Write: Delete/Restore/Purge) | Complete | \~18-24 | 2026-06-02 | *** ## Completed Sessions 1. `phase19-session01-mission-control-write` - Mission Control (Write: Create/Optimize/Tick/Clear), completed 2026-06-02 2. `phase19-session02-documents-gallery-write` - Documents Gallery (Write: Delete/Restore/Purge), completed 2026-06-02 *** ## Upcoming Sessions * None. Phase 19 is complete. *** ## Objectives 1. Add the Mission Control tab with mission view (read) and create/optimize/tick/ clear writes; the optimize write is command-exec and gets the strictest spawn treatment. 2. Add the Documents Gallery tab with list/preview (read) and soft-delete/ restore/purge writes routed through the hook layer (no raw `setInterval`). *** ## Prerequisites * Phase 16 completed (missions and documents read/write endpoints registered with security tests; hooks/types/demo fixtures present). * Phases 17-18 completed (shell, tab framework, and prior write surfaces). *** ## Technical Considerations ### Architecture New tabs are added through `hermes-read-only-page.tsx` (TabsList `:150`, TabsContent `:177-189`). Mission Control's Athena video loop and confetti are presentational. The Documents Gallery's 5s polling goes through the hook layer (React Query refetch), not a raw `setInterval`. All mutations go through `useHermesAdmin`; destructive ops use soft-delete/confirm. ### Source -> Target (per session) **Session 01 (Mission Control, write feature):** * Source: `V23/src/components/hermes-mission-control.tsx` (2,365 lines; writes tick `:611`, clear `:634`). Mission surface, Athena video loop, confetti. * Target: new `AIOS/src/components/hermes/hermes-mission-control.tsx`. * Needs missions GET (read) + create/optimize/tick/clear writes (Write Inventory #2-5), all landed in Phase 16 Session 02: * \#2 Mission optimize -- V23 `vite.config.ts:804` -- **cmd exec**, clones the chat spawn path (`hermes-admin-bridge.ts:696`). * \#3 Mission create -- V23 `:952` -- FS write, `confinePath` to missions file. * \#4 Mission tick -- V23 `:1054`, client `hermes-mission-control.tsx:611` -- FS write, confined, validate goal id. * \#5 Mission clear -- V23 `:1103`, client `hermes-mission-control.tsx:634` -- FS delete, confirm, confined. * All mutations admin-gated through `useHermesAdmin`. Athena video (`claude-art/mission-claude.mp4`, already copied) and confetti (`canvas-confetti` ^1.9.4, already present) are presentational. **Session 02 (Documents Gallery, write feature):** * 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/`, 5s polling. * Target: new `AIOS/src/components/hermes/hermes-documents-gallery.tsx`. * List/preview = read (`/__hermes_documents` GET/file/trash, V23 `:2832` / `:2843` / `:3009`). Writes = admin-gated (Write Inventory #13-15): * \#13 Document soft-delete -- V23 `:2914`, client gallery `:428` -- FS move->trash, name confined, reversible. * \#14 Document restore -- V23 `:2952`, client gallery `:459,1094` -- FS move, trashId confined. * \#15 Document purge -- V23 `:3049`, client gallery `:1118,1141` -- FS delete (permanent), trashId confined, confirm. * 5s polling via the hook layer, not a raw `setInterval`. * Consumes the already-copied `src/assets/hermes-art/file-types/*.webp` set (all 10: pdf/html/markdown/text/data/video/audio/archive/code/other). ### Risks * **Mission optimize executes a command** (Write Inventory #2, highest-risk): Mitigation -- args-array spawn, binPath verify, timeout, output cap, redaction; dedicated security tests asserting inert argv and timeout kill. * **Document purge is permanent deletion**: Mitigation -- trashId confined + confirm; soft-delete moves to a trash dir with a restore path first. * **Polling bypasses the hook layer**: Mitigation -- use React Query refetch interval, not a raw `setInterval` (enforced in Phase 20 cleanup too). ### Relevant Considerations * \[P04] **Hermes bridge guardrails must stay intact**: writes stay behind loopback + token + admin mode; destructive ops confirm. * \[P11] **Privacy boundary on status/output**: no raw paths, command bodies, or private file contents in responses or logs. ### Open Questions Owned By This Phase * **Documents root (Session 02):** resolved in-session by keeping the fixed `~/Documents/Hermes/` path for v1 with the existing `HERMES_DOCUMENTS_DIR` override; the path remains `confinePath`-bounded. *** ## Success Criteria Phase complete when: * [x] Both sessions completed and validated. * [x] Mission Control renders the mission view and performs create/optimize/tick/clear (admin-gated); optimize uses args-array spawn with timeout and passes spawn security tests. * [x] Documents Gallery lists/previews and performs soft-delete/restore/purge (admin-gated, confined, confirmed on purge); polling runs through the hook layer. * [x] Mode matrix renders for both surfaces; typecheck, lint, and tests pass. *** ## Dependencies ### Depends On * Phase 16: Hermes v2.3 Port Foundation * Phase 17: Hermes Shell And Core Writes * Phase 18: Hermes Memory And Visualization ### Enables * Phase 20: Hermes Long-Tail And Parity Sign-off --- # 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/prd_phase_19.md?ask=&goal= ``` `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.