> 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_25/prd_phase_25.md). # PRD\_phase\_25 ## PRD Phase 25: Hermes Mission Control Activation **Status**: Complete **Sessions**: 9 (initial estimate) **Estimated Duration**: 9-12 days **Progress**: 9/9 sessions (100%) *** ### Overview Phase 25 turns the source-verified Hermes Mission Control comparison folded below into an implementation phase. The phase keeps the AI OS typed, modular, admin-gated Hermes architecture while restoring the product-critical Mission Control loop from Claude OS v2.3: deep planning prompts, explicit preview-to-commit semantics, multi-goal authoring, actionable per-goal prompts and briefings, active mission execution hierarchy, archive management, Claude Code parity, and contract documentation. The phase outcome is binary: `/agents/hermes` and `/agents/claude-code` either provide the full orchestration loop on top of the existing AI OS safety model, or the phase is not complete. *** ### Progress Tracker | Session | Name | Status | Est. Tasks | Validated | | ------- | ------------------------------------------- | ----------- | ---------- | --------- | | 01 | Mission Write Contract Preview Commit | Completed | \~12-25 | PASS | | 02 | Mission Schema Version Legacy Compatibility | Completed | \~12-25 | PASS | | 03 | Safe Planning Prompt Authorized Write | Completed | \~12-25 | PASS | | 04 | Multi-goal Authoring Preview UI | Completed | \~12-25 | PASS | | 05 | Full Prompt Drawer Copy Briefings | Completed | \~12-25 | PASS | | 06 | Active Mission Rail Progress | Completed | \~12-25 | PASS | | 07 | Mission Archive Actions | Completed | \~12-25 | PASS | | 08 | Claude Code Parity Responsive E2E | Completed | \~12-25 | PASS | | 09 | Documentation Validation Release | Not Started | \~12-25 | - | *** ### Completed Sessions 1. `phase25-session01-mission-write-contract-preview-commit` - completed and validated. 2. `phase25-session02-mission-schema-version-legacy-compatibility` - completed and validated. 3. `phase25-session03-safe-planning-prompt-authorized-write` - completed and validated. 4. `phase25-session04-multi-goal-authoring-preview-ui` - completed and validated. 5. `phase25-session05-full-prompt-drawer-copy-briefings` - completed and validated. 6. `phase25-session06-active-mission-rail-progress` - completed and validated. 7. `phase25-session07-mission-archive-actions` - completed and validated. 8. `phase25-session08-claude-code-parity-responsive-e2e` - completed and validated. *** ### Upcoming Sessions * None. Phase 25 is complete. *** ### Objectives 1. Fix Mission Control write semantics by making optimize return a non-persisted preview and adding an explicit admin-gated commit path. 2. Version and harden mission storage so legacy and v2.3-shaped mission files normalize safely through the AI OS read contract. 3. Restore the long-form planning prompt and safe agent-authored mission flow without weakening loopback, token, admin-mode, non-demo, or hook-mediated write gates. 4. Replace the one-goal create form with multi-goal authoring and an optimized preview UI that requires explicit operator commit. 5. Surface `full_prompt` on every mini-goal with copy actions, `/goal` prefix safety for agent cards, and structured human briefing rendering. 6. Upgrade active mission presentation with rail focus, milestone-accurate progress, archive actions, and consistent Hermes/Claude Code behavior. 7. Document and validate the activated contract, safe write mechanism, responsive behavior, accessibility, and security posture. *** ### Prerequisites * Phase 24 completed. * Phase 19 Mission Control and Documents Gallery write surfaces completed. * Phase 23 Claude Code route and Mission Control reuse completed. * Source-verified comparison folded into this Phase 25 PRD and session stubs. * Existing Hermes read/admin bridge tests and typed contract tests available. *** ### Technical Considerations #### Architecture Keep the AI OS architecture authoritative. Route files stay thin, Mission Control remains a modular component, reads flow through `useHermes`, writes flow through `useHermesAdmin`, and bridge behavior stays under `scripts/lib/`. v2.3 source is a product reference for orchestration affordances, not a file copy target. Every new write surface must keep the existing admin preflight: * Loopback request. * Valid per-run `X-Claude-OS-Token`. * `HERMES_DASHBOARD_ADMIN=1`. * Non-demo UI mode. * Hook-mediated browser path. #### Technologies * React 19 and TypeScript. * TanStack Router, TanStack Query, and existing Hermes query keys. * Vite/TanStack local dev bridge modules in `scripts/lib/`. * Vitest, Testing Library, and Playwright for contract, component, route, and responsive/e2e coverage. #### Risks * Weakening the admin gate while restoring agent-authored mission creation: preserve the existing preflight and add tests for rejected snippets or unauthorized commits. * Optimized mission ambiguity: split optimize preview from commit so operators never see silent success without active state change. * Dense Mission Control UI: keep manual authoring, optimize preview, active execution, and archive views visually separated. * Token exposure in generated commands: redact or scope any authorized snippet and never log token-shaped values. * v2.3 compatibility drift: normalize old mission files through AI OS bridge contracts without pretending raw v2.3 endpoint envelopes are supported. #### Relevant Considerations * \[P04] **Hermes bridge guardrails must stay intact**: All sensitive reads and opt-in writes must keep loopback plus token checks, no-clobber path safety, and disabled-by-default admin mode. * \[P20] **Long-tail Hermes surfaces stay modular and prop-driven**: Keep Mission Control sections focused so hook-layer contracts remain easy to verify. * \[P23] **Hermes hook reuse for related agent routes**: Hermes and Claude Code Mission Control presentations should share the same contract and differ only in typed presentation copy. * \[P17] **Reuse existing hook contracts for write surfaces**: Extend `useHermes` and `useHermesAdmin` instead of adding component-level fetches. *** ### Success Criteria Phase complete when: * [x] All 9 sessions completed. * [x] Optimize produces a preview; commit persists and activates; no silent success path remains. * [x] Mission documents are versioned and legacy/v2.3-shaped files normalize safely. * [x] Long-form planning prompts exist for Hermes and Claude Code and never instruct tokenless writes. * [x] Multi-goal mixed-actor missions can be authored manually or via optimize-then-commit. * [x] Every mini-goal exposes `full_prompt`; agent cards copy a valid `/goal` prompt and human cards copy a readable briefing. * [x] Active mission execution has rail focus, milestone-aligned progress, and archive reactivation. * [x] Hermes and Claude Code routes are at feature parity and copied prompts are overflow-safe on desktop and mobile. * [x] Docs, full test suite, accessibility review, security review, and admin gate verification pass. *** ### Dependencies #### Depends On * Phase 19: Hermes Orchestration And Documents * Phase 23: Non-Hermes Routes, Polish And Closeout * Phase 24: Trend Finder Outlier Signal Upgrade * Folded source-verified comparison record in this Phase 25 PRD and the matching session stubs. #### Enables * A complete Mission Control execution loop for Hermes and Claude Code. * Future mission storage migration or kanban/task-backed mission surfaces. * Future local-agent orchestration improvements that can reuse the same admin-gated commit model. *** ### Source Project Reference Links #### AI OS * [Hermes route](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/src/routes/agents.hermes.tsx) * [Hermes page shell](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/src/components/hermes/hermes-read-only-page.tsx) * [Mission Control UI](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/src/components/hermes/hermes-mission-control.tsx) * [Claude Code mission page](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/src/components/hermes/claude-code-mission-page.tsx) * [Hermes read hook](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/src/hooks/use-hermes.ts) * [Hermes admin hook](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/src/hooks/use-hermes-admin.ts) * [Hermes read contracts](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/src/lib/hermes-types.ts) * [Hermes admin contracts](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/src/lib/hermes-admin-types.ts) * [Hermes read bridge](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/scripts/lib/hermes-dev-bridge.ts) * [Hermes admin bridge](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/scripts/lib/hermes-admin-bridge.ts) * [Hermes demo fixtures](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/src/lib/hermes-demo-data.ts) #### Claude OS v2.3 Reference * [Reference Hermes route](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.3/src/routes/agents.hermes.tsx) * [Reference Mission Control component](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.3/src/components/hermes-mission-control.tsx) * [Reference Vite middleware/endpoints](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.3/vite.config.ts) * [Reference Documents Gallery](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.3/src/components/hermes-documents-gallery.tsx) * [Reference Mnemosyne component](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.3/src/components/hermes-mnemosyne.tsx) * [Reference README](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.3/README.md) * [Reference CHANGELOG](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.3/CHANGELOG.md) *** ### Folded Source-Verified Comparison Record This section preserves every detail from the old ongoing-project comparison document so that source document can be deleted after this phasebuild correction. The record below is intentionally copied in full, including the source project paths, reference file anchors, source verification log, findings, endpoint comparisons, prompt anatomy, session plan, coverage traceability, and definition of fully activated. ## Hermes Mission Control Comparison > **Status:** Findings (source-verified) **Captured:** 2026-06-08 **Verified:** 2026-06-08 - every claim below was re-checked against the actual source in both trees; line citations are given where a finding turns on specific code. See Appendix B for the verification log. **Scope:** Compare AI OS `/agents/hermes` Hermes orchestration and Mission Control against `/home/aiwithapex/projects/claudeos/claude-os-v2.3/`. **Intent:** Identify what AI OS has strengthened, what v2.3 still does better, and which gaps should become follow-up work. *** ### Executive Summary AI OS has not copied the Claude OS v2.3 Hermes page. It has rebuilt the Hermes surface as a modular local-agent cockpit with typed hooks, typed response parsers, bridge modules, admin-gated write actions, demo fixtures, and broad tests. This is a stronger platform architecture than the reference repo. The tradeoff is that AI OS currently under-delivers on the original Mission Control product loop. Claude OS v2.3 treated Mission Control as an orchestration layer above `/goal`: a detailed prompt guided Hermes through goal discovery, mission decomposition, mixed human/agent mini-goals, authored per-goal execution prompts, and a local dashboard POST. AI OS stores the same core mission fields, but its UI currently exposes only a short starter prompt, a one-goal manual create form, an optimize form, and tick/clear controls. It does not expose the per-mini-goal `full_prompt` briefing that makes the cards actionable. The current AI OS implementation is safer, more testable, and more portable inside the host app. The reference implementation is richer as a mission orchestration experience. The next good step is not to revert to v2.3, but to bring back the product-critical orchestration affordances inside the AI OS contracts. *** ### Sources Inspected #### AI OS | Area | Source | | -------------------------- | ------------------------------------------------------------------------ | | Hermes route wrapper | `src/routes/agents.hermes.tsx` | | Hermes page shell and tabs | `src/components/hermes/hermes-read-only-page.tsx` | | Mission Control UI | `src/components/hermes/hermes-mission-control.tsx` | | Read hook | `src/hooks/use-hermes.ts` | | Admin/write hook | `src/hooks/use-hermes-admin.ts` | | Read contracts | `src/lib/hermes-types.ts` | | Admin contracts | `src/lib/hermes-admin-types.ts` | | Public read bridge | `scripts/lib/hermes-dev-bridge.ts` | | Admin bridge | `scripts/lib/hermes-admin-bridge.ts` | | Demo fixtures | `src/lib/hermes-demo-data.ts` | | Current docs | `README.md`, `docs/agent-pages.md`, `docs/data-contract.md` | | Spec history | `.spec_system/archive/sessions/phase19-session01-mission-control-write/` | #### Claude OS v2.3 Reference | Area | Source | | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Hermes route and most Hermes UI | `/home/aiwithapex/projects/claudeos/claude-os-v2.3/src/routes/agents.hermes.tsx` | | Mission Control component | `/home/aiwithapex/projects/claudeos/claude-os-v2.3/src/components/hermes-mission-control.tsx` | | Vite middleware/endpoints | `/home/aiwithapex/projects/claudeos/claude-os-v2.3/vite.config.ts` | | Documents and Mnemosyne components | `/home/aiwithapex/projects/claudeos/claude-os-v2.3/src/components/hermes-documents-gallery.tsx`, `/home/aiwithapex/projects/claudeos/claude-os-v2.3/src/components/hermes-mnemosyne.tsx` | | README/changelog | `/home/aiwithapex/projects/claudeos/claude-os-v2.3/README.md`, `/home/aiwithapex/projects/claudeos/claude-os-v2.3/CHANGELOG.md` | *** ### Current AI OS Shape AI OS exposes `/agents/hermes` through a very thin TanStack route wrapper. The route delegates the whole page to `HermesReadOnlyPage`, and page metadata now frames Hermes as a host-cockpit local telemetry surface rather than the entire product shell. The Hermes page mounts these tabs: * Overview * Sessions * Chat * Mission * Documents * Memory * Mnemosyne * Pantheon * Skills * Admin The page owns demo/live mode, the selected chat session, the `useHermes` read hook, the `useHermesAdmin` write hook, and fixture substitution. The Mission tab receives `missions`, `admin`, and `demoMode` as props. `useHermes` separates public bridge reads from token-gated sensitive reads: * Public/local reads after Hermes is detected: status, models, connections, Pantheon templates, missions, document summaries, document trash, document file previews. * Token-gated reads after the per-run token succeeds: sessions, session detail, memory, Pantheon personas, skills, profiles. `useHermesAdmin` centralizes all writes and mutation state. Mission writes are exposed as: * `createMission` * `optimizeMission` * `tickGoal` * `clearMission` The admin hook also handles chat streaming, image upload, Pantheon writes, Pantheon mirror sync, document delete/restore/purge, and Obsidian linking. The dev bridges are split: * `hermes-dev-bridge.ts` handles loopback-only reads and only checks the per-run token for sensitive read endpoints. * `hermes-admin-bridge.ts` handles writes and requires loopback, the per-run `X-Claude-OS-Token`, and `HERMES_DASHBOARD_ADMIN=1`. This split is a major architectural improvement over the reference. *** ### Reference v2.3 Shape Claude OS v2.3 keeps much more behavior inside route/component files: * `src/routes/agents.hermes.tsx` is 7,364 lines. * `src/components/hermes-mission-control.tsx` is 2,365 lines. * `vite.config.ts` owns a large amount of local middleware (3,298 lines), including Hermes status, chat, mission, Pantheon, documents, skills, and token routes. * No `*.test.*`, `*.spec.*`, or `__tests__` files were found in the reference tree. The size contrast makes the architectural difference concrete. AI OS spreads the same surface across many small, single-purpose modules; v2.3 concentrates it in three very large files. | Concern | AI OS module(s) | Lines | v2.3 location | Lines | | ------------------------ | ---------------------------------------------------- | ----: | ------------------------------------------- | -------: | | Route entry | `src/routes/agents.hermes.tsx` | 16 | `src/routes/agents.hermes.tsx` | 7,364 | | Page shell | `src/components/hermes/hermes-read-only-page.tsx` | 462 | (inside the route file) | - | | Mission Control UI | `src/components/hermes/hermes-mission-control.tsx` | 1,421 | `src/components/hermes-mission-control.tsx` | 2,365 | | Claude Code mission page | `src/components/hermes/claude-code-mission-page.tsx` | 321 | (same component, `agent` prop) | - | | Read hook | `src/hooks/use-hermes.ts` | 584 | (inline `fetch` in route/component) | - | | Admin/write hook | `src/hooks/use-hermes-admin.ts` | 865 | (inline `fetch` in component) | - | | Read contracts | `src/lib/hermes-types.ts` | 753 | (local `interface` blocks) | - | | Admin contracts | `src/lib/hermes-admin-types.ts` | 582 | (local `interface` blocks) | - | | Read bridge | `scripts/lib/hermes-dev-bridge.ts` | 1,698 | `vite.config.ts` middleware | 3,298 | | Admin/write bridge | `scripts/lib/hermes-admin-bridge.ts` | 2,041 | `vite.config.ts` middleware | (shared) | | Demo fixtures | `src/lib/hermes-demo-data.ts` | 449 | (none) | - | | Tests | 15 Hermes-related validation files | - | none found | 0 | The AI OS Mission Control component is not a thin status panel: at 1,421 lines it already implements forms, validation, redaction, optimistic ticking, confetti, and a full state machine. The product gap below is therefore about *missing affordances* (per-goal briefings, multi-goal authoring, a real planning prompt), not about a lack of engineering investment. Mission Control in v2.3 is a standalone product experience. The component comments describe one consolidated panel: * Empty state: copy a short-term or long-term prompt. * The long-term prompt tells Hermes to interrogate the goal, decompose it, and POST the mission to the dashboard. * The dashboard polls `~/.hermes/missions.json` while empty and renders the mission when Hermes writes it. * Active state: render the mission card, progress bar, mini-goal cards, copy prompts, completion ticks, and clear/drop control. The v2.3 Mission Control prompt is much more than placeholder copy. It encodes the mission model: * A mission is a binary 7-42 day outcome. * Each mission has 4-10 mini-goals, usually 5-7. * Each mini-goal has exactly one actor: agent/Hermes or human. * Agent cards should produce `/goal` prompts. * Human cards should produce structured briefings. * Discovery questions are required before decomposition. * The agent should POST the resulting JSON to the dashboard endpoint. That prompt and the per-card copy behavior are the reference system's biggest product strengths. *** ### Architecture Comparison | Dimension | AI OS current | Claude OS v2.3 reference | Finding | | ------------------ | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------- | | Route ownership | Thin route plus extracted page and components. | Large route owns most Hermes surface. | AI OS is more maintainable and easier to test. | | Data fetching | `useHermes` hook with query keys, parsers, public/sensitive split, demo substitution. | Direct `fetch` calls and local hooks embedded in large files. | AI OS has a clearer data boundary. | | Writes | `useHermesAdmin` centralizes mutation state and admin gating. | Direct `fetch` calls from components plus Vite middleware. | AI OS is safer and less duplicated. | | Middleware | Split read/admin bridge modules under `scripts/lib/`. | Large Vite config middleware block. | AI OS is easier to reason about and test. | | Type contracts | Read/admin response parsers reject malformed payloads. | Local interfaces and ad hoc JSON parsing. | AI OS has stronger runtime contract checks. | | Tests | Dedicated bridge, parser, hook, component, route, and e2e tests. | No test files found in checked reference tree. | AI OS has much better confidence surface. | | Product prompt | Short starter prompt and forms. | Detailed orchestration prompt with discovery/decomposition/POST rules. | v2.3 has a stronger Mission Control product loop. | | Per-goal execution | Current UI shows done-when and tick controls, but not `full_prompt` copy. | Per-card copy and briefing drawer are central. | v2.3 is much more actionable for operators. | *** ### Mission Data Contract Both systems use the same broad mission file idea: ``` ~/.hermes/missions.json { "active": "", "missions": { "": { "title": "...", "binary_outcome": "...", "deadline_days": 28, "deadline_iso": "...", "created_at": "...", "mini_goals": [...] } } } ``` AI OS formalizes this into typed read and admin contracts: * `HermesMissionGoal` * `HermesMissionSummary` * `HermesMissionsBody` * `HermesMissionCreateRequest` * `HermesMissionOptimizeRequest` * `HermesMissionTickRequest` * `HermesMissionClearRequest` * `HermesMissionWriteBody` * `HermesMissionClearBody` AI OS read responses require `ok: true`, `active`, `mission`, `total`, and `missions`. Claude OS v2.3 read responses return only `{ mission }` for the mission GET endpoint. This is an intentional AI OS contract hardening, but it means the current parser is not wire-compatible with the raw v2.3 endpoint shape. AI OS also normalizes malformed or legacy mission files through the read bridge. A raw goal status other than `"done"` becomes `"queued"`. v2.3 had a local type that included `"active"`, but its tick behavior primarily toggled between `"queued"` and `"done"`. The AI OS status set is simpler. There is current limit drift that follow-up work should resolve deliberately: the v2.3 product prompt targets `deadline_days` 7-42 and 4-10 mini-goals, the AI OS starter prompt asks for 3-5 mini-goals, the AI OS manual create UI accepts deadlines from 1-90 days, and the AI OS bridges clamp mission deadlines to 1-365 days while accepting 1-10 mini-goals on writes and normalizing up to 20 goals on reads. The plan below uses the v2.3 limits as the product target, but the implemented contract should make the final range explicit. *** ### Mission Control UX Comparison #### v2.3 Strengths The v2.3 Mission Control UI is built around action: * It gives the operator a long-form prompt that actually creates a mission through the dashboard. * It requires discovery before decomposition, which reduces generic `done_when` fields. * It enforces mixed human/agent mini-goals at the prompt layer. * It instructs the model to author full prompts for every mini-goal. * It exposes per-goal copy behavior so agent cards can be pasted into Hermes or Claude Code and human cards can be used as briefings. * It shows a richer active mission presentation: one-goal-at-a-time rail, briefing overlay, copy buttons, mark-complete buttons, progress, estimates, and strong visual hierarchy. Grounded in the actual `hermes-mission-control.tsx` component, the v2.3 execution affordances are: * `BriefingDrawer` - clicking a mini-goal card swaps the fixed-height rail stage into a full briefing drawer; the page underneath does not shift or scroll-jump. * `buildCopyText(goal, mission, index, total, opName)` - shared by each card's Copy button and the drawer. For agent goals it emits the `/goal`-prefixed prompt; for human goals it emits the briefing, and it appends an explicit guard line: "Do NOT mark Mission Control complete yourself - I'll tick it in the panel." * `formatHumanBrief` - parses the Hermes-authored human briefing into labeled sections for display, falling back gracefully to prose if unstructured. * A flowing-gradient progress bar whose fill geometry uses the exact decimal (`done / total * 100`) so the fill ends precisely under the milestone tick of the current goal; rounding happens only at the label. * Per-card `Mark-complete` tick that POSTs to `/__hermes_missions/tick`. These are exactly the affordances AI OS has not yet rebuilt. AI OS's `GoalCard` (`hermes-mission-control.tsx` lines 884-959) renders `num`, `title`, `done_when` (via `ClipText`), `estimate`, `status`, and a tick button - but no `full_prompt`, no copy button, and no drawer. #### AI OS Strengths The AI OS Mission Control tab is better as an app surface: * It participates in the broader Hermes tab framework. * It handles explicit loading, empty, success, error, offline, token-failure, and demo states. * It exposes admin-gate state in the UI. * It prevents duplicate mutation triggers through `useHermesAdmin` and local busy state. * It requires an explicit text confirmation before clearing active mission. * It scopes errors through bounded/redacted display helpers. * It uses query invalidation rather than local polling/fetch bypasses. * It has focused component tests and route coverage. #### AI OS Product Regressions The current AI OS Mission Control UI loses several orchestration affordances from v2.3: 1. It does not expose `full_prompt` on mini-goal cards. The data model and bridge preserve `full_prompt`, but `GoalCard` only shows title, actor, `done_when`, estimate, status, and tick control. This makes agent mini-goals less actionable. 2. The empty-state prompt is too small to recreate the v2.3 planning flow. The current `START_PROMPT` asks for a bounded mission with 3-5 mini-goals, but it does not include discovery rules, actor decision rules, `full_prompt` rules, or dashboard POST instructions. 3. Manual create only captures one human mini-goal. The create form builds a mission with one `actor: "human"` mini-goal. It cannot author multiple goals, choose the actor, or enter `full_prompt` details through the UI. 4. Optimized missions are not visibly applied. The admin bridge currently creates and returns a mission document from Hermes optimize output, but the inspected code does not persist that mission to `missions.json` before returning. The component shows an optimize success message and invalidates the mission query, but the active mission state will not change unless some other path writes the mission. 5. The operator cannot copy a per-card `/goal` prompt. v2.3 treated this as the bridge between planning and execution. AI OS has no equivalent per-card copy or briefing drawer in the current Mission tab. *** ### Safety Comparison AI OS is substantially stronger on local write safety. #### AI OS Safety Model Mission writes require all of: * Loopback request. * Valid per-run `X-Claude-OS-Token`. * `HERMES_DASHBOARD_ADMIN=1`. * Non-demo mode in the UI. * Hook-mediated mutation path. The admin bridge preflight applies this consistently to mission create, optimize, tick, and clear. Clear also requires a confirmation payload. The UI also requires typing `clear` before invoking the clear mutation. #### v2.3 Safety Model The v2.3 Vite middleware has loopback checks, and some endpoints check the per-run token. The mission create and clear comments explicitly treat loopback-only as the boundary so Hermes can curl the dashboard without reading the token. In the inspected v2.3 middleware: * `GET /__hermes_missions` is loopback-only. * `POST /__hermes_missions/optimize` checks loopback and token. * `POST /__hermes_missions/create` is loopback-only, no token. * `POST /__hermes_missions/tick` is loopback-only, no token. * `POST /__hermes_missions/clear` is loopback-only, no token. That made the agent-driven mission POST easy, but it also widened the local write surface. AI OS has correctly tightened this. #### Security Tradeoff The tightened AI OS admin gate creates a product gap: the old "paste this to Hermes and let it POST the mission" flow no longer works unless the agent can obtain or receive an authorized write mechanism. This should be resolved deliberately rather than by weakening the admin bridge. Good options: * Keep direct agent POST disabled and make Mission Control explicitly manual. * Provide a user-copied, short-lived authorized curl command that includes the same-run token and expires with the dev server process. * Use the existing admin chat path to ask Hermes to produce mission JSON, then have the UI persist it through the already-authorized browser/admin hook. * Add an "optimized preview" state where the returned mission is visible and the operator clicks "Set active mission." The last two options preserve the safety model while restoring the v2.3 workflow. *** ### Endpoint Comparison | Endpoint | AI OS current | Claude OS v2.3 reference | Finding | | ----------------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------ | | `/__hermes_status` | Read bridge module, loopback-only. | Vite config middleware, loopback-only. | Same role; AI OS is modular. | | `/__token` | Used by hooks for sensitive reads/admin writes. | Used by route/component fetches. | Same concept; AI OS has cleaner propagation. | | `/__hermes_missions` GET | Returns `ok`, `active`, `mission`, `total`, `missions`; public local read. | Returns `{ mission }`; public local read. | AI OS supports archive/list and typed parsing, but not raw v2.3 compatibility. | | `/__hermes_missions/create` | Admin bridge, token plus admin env required, writes active mission. | Loopback-only, no token, writes active mission. | AI OS is safer; v2.3 enabled direct agent curl. | | `/__hermes_missions/optimize` | Admin bridge, token plus admin env required, shells Hermes via argv array, returns mission. | Token required, shells Hermes, returns mission. | AI OS is safer but appears not to persist returned mission. | | `/__hermes_missions/tick` | Admin bridge, token plus admin env required, toggles active goal. | Loopback-only, no token, toggles active goal. | AI OS is safer. | | `/__hermes_missions/clear` | Admin bridge, token plus admin env required, confirmation body required, clears active id. | Loopback-only, no token, clears active id. | AI OS is safer and has better UI confirmation. | *** ### Testing Comparison AI OS has a much stronger validation envelope. The current Hermes-related validation files are: * `scripts/lib/__tests__/hermes-admin-bridge.test.ts` * `scripts/lib/__tests__/hermes-dev-bridge.test.ts` * `scripts/lib/__tests__/hermes-scanner.test.ts` * `src/components/hermes/__tests__/hermes-documents-gallery.test.tsx` * `src/components/hermes/__tests__/hermes-mission-control.test.tsx` * `src/components/hermes/__tests__/hermes-mnemosyne.test.tsx` * `src/components/hermes/__tests__/hermes-sections.test.tsx` * `src/components/hermes/__tests__/hermes-status-pill.test.tsx` * `src/components/hermes/chat/__tests__/hermes-chat-tab.test.tsx` * `src/hooks/__tests__/use-hermes.test.tsx` * `src/hooks/__tests__/use-hermes-admin.test.tsx` * `src/lib/__tests__/hermes-types.test.ts` * `src/lib/__tests__/hermes-admin-types.test.ts` * `src/routes/__tests__/agents.test.tsx` * `tests/e2e/hermes-agent.spec.ts` The route test is shared agent-route coverage, but it exercises the Hermes route. The Claude OS v2.3 tree inspected here has no test files. The reference may have been useful as product exploration, but AI OS is the version with enforceable contracts. Coverage that AI OS already has: * Admin disabled state. * Token failure state. * Duplicate mutation prevention. * Mission create/optimize/tick/clear behavior. * Bridge preflight across write inventory. * Path confinement and confirmation checks. * Demo/live tab wiring. * Browser coverage for the Mission tab with mocked data. Coverage that should be added if follow-up work lands: * Optimize persists or produces a visible preview, depending on product decision. * Per-goal `full_prompt` copy behavior. * Multi-goal create/editor behavior. * Authorized agent-to-dashboard mission creation, if restored. * Compatibility normalization for legacy v2.3 mission payloads, if desired. *** ### Detailed Findings #### 1. AI OS Is Architecturally Better For A Platform AI OS has decomposed Hermes into route, page, feature components, hooks, contracts, bridges, fixtures, and tests. That matches the broader AI OS direction: Hermes is one local-agent cockpit inside the host product. This should be preserved. Copying the v2.3 monolith back into AI OS would be a regression. #### 2. v2.3 Is Product-Richer For Mission Orchestration The v2.3 long prompt and per-card copy UX are not ornamental. They are the mechanism that turns a mission board into an execution system. Without them, Mission Control mostly becomes a mission status panel. AI OS should restore these affordances through the current architecture. #### 3. AI OS Has A Confirmed Optimize-Write Bug This is no longer "possible" - it is confirmed by direct line comparison in `scripts/lib/hermes-admin-bridge.ts`. Three of the four mission write handlers persist before responding; optimize does not: * `handleMissionCreateRequest` - `store.missions[mission.id] = mission; store.active = mission.id; await writeMissionStore(options, store)` (lines 1421-1423), then `201 { ok: true, mission }`. * `handleMissionTickRequest` - toggles `goal.status` then `await writeMissionStore(options, store)` (line 1463). * `handleMissionClearRequest` - `store.active = null; await writeMissionStore(options, store)` (lines 1488-1489). * `handleMissionOptimizeRequest` - shells Hermes, builds `createMissionDocument(extractJsonObject(result.stdout))`, then immediately `sendJson(res, 200, { ok: true, mission })` **with no `readMissionStore` / `writeMissionStore` call at all** (lines 1549-1551). So optimize returns a freshly minted mission object to the browser, but never writes it to `~/.hermes/missions.json` and never sets it active. The UI (`hermes-mission-control.tsx` `handleOptimize`, lines 1213-1247) checks only `result?.mission`, reports `optimizeSuccessMessage`, closes the form, and calls `invalidateMissions()`. The invalidation re-reads the unchanged store, so the active mission does not change. The operator sees a green success state and no new mission. (Manual create works precisely because it does persist.) Recommended decision: * If optimize means "set an optimized mission," persist it and make it active. * If optimize means "generate a candidate," render the returned mission as a preview and require a separate "Set active" action. The current behavior should not remain ambiguous. #### 4. AI OS Stores `full_prompt` But Does Not Use It `full_prompt` exists in read and admin mission contracts, is accepted by the bridge, and appears in demo data. The Mission Control card UI does not surface it. This is the clearest gap against v2.3. Recommended work: * Add a mini-goal detail drawer or expandable panel. * Show `full_prompt` with strong wrapping and bounded height. * Add copy behavior: * Hermes/agent goals: "Copy /goal prompt" * Human goals: "Copy briefing" * Preserve the safety rule from v2.3: agent prompts should start with `/goal` when applicable, or the UI should warn if they do not. #### 5. Manual Mission Creation Is Too Weak The current create form creates one human mini-goal. That is useful as a smoke test of the write path, but not enough for real Mission Control. Recommended work: * Add dynamic mini-goal rows. * Support actor selection for each goal. * Support `done_when`, estimate, and optional `full_prompt`. * Enforce a reasonable minimum and maximum in the UI, aligned with the bridge. * Consider "manual lightweight" and "optimized from prompt" as two separate modes so the UI does not become too dense. #### 6. Agent-Driven Mission Creation Needs A New Safe Mechanism v2.3 intentionally allowed local Hermes to curl `create` without a token. AI OS correctly removed that by requiring token and admin gate for all mission writes. That means the old copied long prompt cannot be reused unchanged. Recommended work: * Do not weaken admin preflight. * Rebuild the copied prompt around an authorized UI-mediated flow: * The operator asks Hermes through the Chat tab. * Hermes returns mission JSON. * The UI validates and persists through `useHermesAdmin`. * Or generate a short-lived authorized curl snippet from the browser for explicit operator copy/paste. #### 7. Contract Hardening Created Compatibility Drift AI OS expects `ok: true` response envelopes and richer mission list payloads. v2.3 endpoints do not provide this shape. Existing v2.3-generated `missions.json` data is likely readable through the AI OS bridge because the bridge normalizes file contents, but raw endpoint compatibility is not present. This is acceptable if AI OS owns the bridge. It should be documented if anyone expects to point the AI OS UI at the old v2.3 dev server. #### 8. AI OS Has Better State Coverage AI OS explicitly renders and tests: * idle * loading * success * empty * error * offline * token-failure * demo * admin-disabled * admin-ready v2.3's UX was strong when live, but its state model was less formal. #### 9. Multi-Agent Reuse Exists In Both - AI OS Did Not Originate It An earlier framing credited AI OS with introducing the agent-neutral Mission Control component. That is not accurate against the source. **v2.3 already does this.** Its component exports `MissionControlAgent = "hermes" | "claude-code"`, takes an `agent` prop, and uses `buildLongPrompt(agent)` to swap only the opening self-address line: * `hermes` -> "You are Hermes acting as my strategic planning partner..." * `claude-code` -> "You are Claude Code acting as my strategic planning partner..." * default (home embed) -> neutral "Either of my agents (Hermes or Claude Code) can run this prompt; the output is identical." The shared mission body in v2.3 is deliberately agent-agnostic, and the `"hermes"` actor tag is documented there as meaning "an agent runs this" (Hermes *or* Claude Code), kept only for schema backwards-compatibility. AI OS mirrors the same idea with `missionControlAgent="claude-code"` and a dedicated `claude-code-mission-page.tsx`, plus the same `"hermes" | "human"` actor set. So the honest finding is: **both systems share the multi-agent design.** AI OS's actual contribution is not the concept but the *typed, tested contract boundary* around it (`hermes-types.ts`, `hermes-admin-types.ts`, parser rejection of malformed payloads). The recommendation stands - keep the shared component agent-neutral at the contract layer and confine agent differences to presentation copy - but it should be stated as preserving a property both systems already have, not as an AI OS innovation. *** ### Recommended Follow-Up Work #### Priority 1 1. Decide and fix `optimizeMission` semantics. Persist the optimized mission as active, or expose it as a preview with a separate "Set active" action. 2. Add per-mini-goal `full_prompt` visibility and copy behavior. This restores the most important execution affordance from v2.3. 3. Restore a safe long-form Mission Control prompt flow. The prompt should include discovery, actor rules, mini-goal limits, `full_prompt` requirements, and safe write instructions compatible with AI OS admin gating. #### Priority 2 4. Replace the one-goal manual create form with a multi-goal editor. Keep it operational and compact; do not recreate the v2.3 monolith. 5. Add compatibility tests for legacy mission files. Include missing `full_prompt`, missing `estimate`, unknown status, active pointer mismatch, malformed mission entries, and archived mission lists. 6. Add route/e2e coverage for copied prompts. Verify no horizontal overflow, long text wrapping, and mobile drawer behavior. #### Priority 3 7. Add mission archive actions. AI OS already reads a mission list. Consider "set active" or "reactivate" for old missions if this becomes useful. 8. Add a mission schema version. This would make future migrations from JSON to task/kanban storage easier. 9. Document the final Mission Control contract in `docs/agent-pages.md` or `docs/api/README_api.md` after follow-up implementation. *** ### Suggested Target UX The target should combine both systems: ``` AI OS architecture + v2.3 orchestration prompt depth + admin-gated write safety + per-goal execution briefings + tested typed contracts ``` Recommended Mission tab layout: 1. Header with active/admin state and refresh. 2. Empty state with three actions: * Copy planning prompt. * Optimize from prompt. * Create manually. 3. Optimized preview state: * Shows proposed title, outcome, deadline, actor split, and mini-goals. * Requires "Set active mission" to persist. 4. Active mission state: * Progress metrics. * Mini-goal cards. * Per-goal detail/copy drawer. * Tick control. * Clear active mission confirmation. 5. Archive list: * Existing mission list. * Optional set-active/reactivate later. This keeps the AI OS implementation disciplined while recovering the v2.3 product feel. *** ### Bottom Line AI OS is the better engineering foundation. Claude OS v2.3 is the better Mission Control product prototype. The right path is to keep the AI OS hook/bridge/admin/test architecture and port the missing v2.3 orchestration affordances: * detailed planning prompt, * safe mission creation flow, * multi-goal authoring, * per-goal `/goal` and human briefing copy, * clear optimize semantics. That would make `/agents/hermes` both safer than v2.3 and meaningfully more useful as Hermes orchestration. *** ### Appendix A: The v2.3 Orchestration Prompt (Anatomy) The single largest product asset in v2.3 is the `LONG_PROMPT_BODY` constant in `src/components/hermes-mission-control.tsx` (the file comment literally calls it "THE PROMPT - paste-into-Hermes-chat copy. This is the whole product"). AI OS's `START_PROMPT` is one sentence; the v2.3 prompt is a multi-step operating contract. Restoring an AI-OS-safe equivalent is Priority 1, so its full structure is documented here. #### Framing and guardrails (top of prompt) * Self-address line chosen by `buildLongPrompt(agent)` (Hermes / Claude Code / neutral). * "This is NOT a /goal run. Don't activate the Ralph loop. Don't start the mini-goals." The model's only job is plan -> decompose -> POST. * "The first and ONLY tool you call is in Step 4 - a curl POST. The HTTP response is the verification. No filesystem tools. No write\_file. No python. Just curl." * Strict output discipline: the operator should see only (1) clarifying / discovery questions as numbered lists and (2) the final "Mission set" confirmation. No internal labels ("Pass 1", "Vet:", "Draft:", "Critique:", "Building curl payload", "Server response:"), no rubric echo, and **no JSON printed in chat** - the payload travels only inside the curl. #### Mission model (the rubric the model enforces) * A mission is a binary, ship-able outcome - YES or NO at the deadline (a number, an artifact, or a revenue figure). * Time horizon 7-42 days (less -> a single `/goal`; more -> strategy, not execution). * 4-10 mini-goals, sweet spot 5-7, **hard cap 10**. * The mission completes only when every mini-goal is checked off. #### The actor rule (the "session boundary") For each candidate mini-goal the model asks exactly one question - can an agent finish this within a working session where the operator is present to pick, tweak, and approve? * **YES** -> actor `"hermes"` (schema name; semantically "an agent runs this", Hermes or Claude Code). * **NO** -> actor `"human"`, reserved for work that needs the operator's body, face, voice, legal name, physical presence elsewhere, OR a third party that blocks progress. Approvals alone do **not** make a card human. The prompt requires a balanced split (between 40/60 and 60/40 agent/human) and re-balances if the union is lopsided. #### Discovery (non-negotiable) Before writing any mini-goal, the model generates **4-8 discovery questions tailored to the specific goal** (current state, constraints, fixed deadlines, dependencies, third parties) and asks them as one numbered list. The prompt is explicit that skipping discovery yields generic `done_when` fields and a wasted mission. #### Silent multi-pass decomposition Done as scratch work, never printed: 1. **Draft** - 4-10 candidates; title <=5 words, actor, `done_when` <=8 words. 2. **Critique** - each title an action phrase; each `done_when` punchy, measurable, and using the discovered state (not generic phrasing); right-sized (agent about 20 turns, human = one session/call/event); self-served (agent has every credential); correct actor. 3. **Completeness + balance** - does the union actually ship the binary outcome, and is the actor split balanced? 4. **Author `full_prompt` for every mini-goal** (see spec below). Then lock the list, pick `deadline_days` (default 28, range 7-42), write a `binary_outcome` (<=12 words) and a 6-8 word mission title. #### The `full_prompt` spec (the copied briefing) `done_when` is the card label; `full_prompt` is the briefing the operator copies into an agent to actually execute the card. * **Agent (`"hermes"`) cards** - a `/goal` slash-command prompt that **must begin with the literal six characters `/goal` (slash, the word, one space)**, with no leading whitespace/markdown/preamble, because the operator pastes it straight into Claude Code or Hermes and a missing prefix means the slash command never fires. It then names the mission/mini-goal/binary outcome, states the deliverable using discovered state (WHAT not WHICH tools), caps at \~20 turns, must not self-tick the Mission Control card, and leaves a one-paragraph summary. 80-250 words, plain text, agent-agnostic wording. * **Human cards** - a structured briefing of 8 labeled sections in order (Headline, ... Definition of done, ...), 120-200 words, written so the human knows what to do in the next 30 seconds; generic placeholders unless discovery gave specifics. The v2.3 prompt later has a shorter human-card placeholder in the sample JSON, but the formal `full_prompt` spec and the v2.3 create-handler validation comment both point back to 120-200 word human briefings. Treat the formal spec as authoritative for the port. #### Step 4 - POST and confirm The model runs one curl in its bash tool: ``` POST http://localhost:8081/__hermes_missions/create { title, binary_outcome, deadline_days, mini_goals: [ { num, title, actor, done_when, full_prompt }, ... ] } ``` * This endpoint in v2.3 is **loopback-only with no token** - that is why the copied prompt can curl it directly. (This is exactly the surface AI OS closed; see the Safety Comparison and Finding #6 - any restored prompt must POST through the AI OS admin-gated path or a UI-mediated flow instead.) * On HTTP success the model prints one confirmation line starting with a checkmark. ASCII-normalized here: `Mission set: "" - <N> mini-goals (<H> for the agent, <M> for you), ship-by <date>.` * On `HTML / 404 / connection refused` it prints one diagnostic line and stops * it must not pretend the mission was set. #### Why this matters for the port Every Priority 1 follow-up item maps onto a piece of this anatomy: the planning prompt (this whole appendix), `full_prompt` visibility/copy (the spec above), discovery-driven `done_when` quality (the discovery + critique passes), and the safe-write requirement (Step 4 re-pointed at the admin bridge). The appendix is intended to be usable as the acceptance checklist for that work. *** ### Appendix B: Verification Log This pass re-read the live source in both trees on 2026-06-08 rather than relying on the prior draft. Primary evidence: | Claim | Evidence | | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | AI OS Mission Control is modular and large (not a stub) | `src/components/hermes/hermes-mission-control.tsx` = 1,421 lines; route wrapper = 16 lines. | | Optimize does not persist | `scripts/lib/hermes-admin-bridge.ts`: create persists at 1421-1423, tick at 1463, clear at 1488-1489; optimize returns at 1549-1551 with no store write. | | `GoalCard` omits `full_prompt` | `hermes-mission-control.tsx` lines 884-959 (renders num/title/done\_when/estimate/status/tick only). | | Manual create is single human goal | `validateCreateDraft` builds one `actor: "human"` mini-goal, lines 464-502. | | `START_PROMPT` is one sentence | `hermes-mission-control.tsx` lines 136-137. | | AI OS read contract is the richer envelope | `scripts/lib/hermes-dev-bridge.ts` lines 1534-1563 (`active`, `mission`, `total`, `missions`); types in `src/lib/hermes-types.ts` lines 181-210. | | AI OS normalizes status to `queued`/`done` | `hermes-dev-bridge.ts` line 696 (`status === "done" ? "done" : "queued"`); `full_prompt` preserved at lines 249/694. | | Both share actor set `"hermes" \| "human"` | AI OS `hermes-admin-types.ts` line 105; v2.3 component `Actor` type + JSON schema notes. | | v2.3 is multi-agent too | v2.3 `hermes-mission-control.tsx`: `MissionControlAgent`, `buildLongPrompt(agent)` lines 515-523. | | v2.3 prompt is "the whole product" | v2.3 `LONG_PROMPT_BODY`, lines 301-509 (anatomy in Appendix A). | | v2.3 create/tick/clear are loopback-only, no token; optimize is token-gated | v2.3 `vite.config.ts`: optimize token check \~804-812; create comment "No token required" \~944-957; tick \~1054; clear "No token required" \~1100-1108. | | v2.3 mission GET returns `{ mission \| null }` | v2.3 `vite.config.ts` comment line 247; component `setMission(j.mission ?? null)` line 551. | | v2.3 per-card copy + briefing overlay exist | v2.3 component: `buildCopyText` 1074-1128, `BriefingDrawer` 1209-1577, `formatHumanBrief` 1130-1196. | | Current limit drift is real | v2.3 prompt targets 7-42 days and 4-10 goals; AI OS starter prompt says 3-5 goals; AI OS manual create validates 1-90 days; AI OS bridges clamp deadlines to 1-365, write up to 10 goals, and read up to 20. | | v2.3 has no checked test files | No `*.test.*`, `*.spec.*`, or `__tests__` files found under the v2.3 reference tree; AI OS has 15 Hermes-related validation files (listed in Testing Comparison). | *** ### Session Plan This plan turns every finding, recommendation, and capability above into an ordered set of implementation sessions. Each session is a self-contained unit of work with its own objective, scope, file targets, build steps, and exit criteria. Completing all sessions in order fully fixes, configures, optimizes, implements, and activates the entire Mission Control surface described in this document - with no regression to the AI OS safety, contract, or state-coverage strengths. #### Reference Source Map Every session below carries a **Reference (v2.3)** line pointing at the exact reference code to mirror. Citations are relative to the reference root `v2.3/` = `/home/aiwithapex/projects/claudeos/claude-os-v2.3/`. Line numbers are the 2026-06-08 inspection snapshot - treat them as anchors and re-confirm before editing. The two reference files that matter for this plan: * `v2.3/src/components/hermes-mission-control.tsx` - the entire Mission Control UI, planning prompt, per-card copy, briefing renderer, and goal rail. Key anchors: `Actor`/`Status`/`MiniGoal`/`Mission` types (265-286); endpoint contract comments (243-249); `LONG_PROMPT_BODY` (313-509); `buildLongPrompt` (511-523); `MissionControlAgent` (532); `refetch` GET (547-555); exact-decimal progress geometry (561-569); tick/clear fetches (610, 633); `EmptyPanel` + `copy()` + Copy-prompt button (783-944); `MissionBody` (945-1034); `estimateToPips` (1035-1073); `buildCopyText` incl. `/goal` safety net (1074-1128); `formatHumanBrief` + `HUMAN_BRIEF_LABELS` (1130-1196); `BriefingDrawer` (1209-1577); `MissionGoalRail` incl. progress bar + milestone ticks (1583-1987). * `v2.3/vite.config.ts` - the local mission endpoints: GET `/__hermes_missions` (778-799), `optimize` (799-943), `create` (944-1050), `tick` (1051-1099), `clear` (1100-1124); `MISSIONS_FILE` (751). Where a session has no reference, the capability has no v2.3 equivalent and is marked **Reference (v2.3): none - AI OS-new**; the AI OS contracts/bridges named in that session are the substrate to build on. #### Phase Outcome (binary) `/agents/hermes` (and the Claude Code mission route) fully restore the v2.3 Mission Control orchestration loop - planning prompt, discovery-driven decomposition, multi-goal authoring, optimized preview -> commit, per-goal `/goal` and human-briefing copy, and archive management - on top of the AI OS typed-contract, admin-gated, tested architecture, with documentation and end-to-end validation. YES/NO at the end of the last session. #### Cross-Cutting Guardrails (every session must hold these) These are the AI OS strengths the plan must preserve while adding v2.3 affordances. No session may regress them: 1. Admin-gate is never weakened. All writes keep requiring loopback + valid per-run `X-Claude-OS-Token` + `HERMES_DASHBOARD_ADMIN=1` + non-demo + hook-mediated path. 2. Typed contracts stay authoritative. New fields/endpoints get read/admin parsers that reject malformed payloads; no ad hoc JSON. 3. State machine stays explicit. idle / loading / success / empty / error / offline / token-failure / demo / admin-disabled / admin-ready all keep rendering and stay tested. 4. Errors stay bounded and redacted through the existing display helpers. 5. Reads use query invalidation, not polling or fetch bypasses. 6. Demo/live parity holds; demo mode never triggers a real write. 7. Both agent presentations (`hermes`, `claude-code`) stay at parity at the contract layer; differences remain presentation copy only. 8. Every new affordance ships with unit/component coverage in the same session; responsive/e2e coverage lands by S25-08. #### Session Sequence | ID | Title | Depends on | | ------ | ----------------------------------------------------------------- | -------------- | | S25-01 | Mission write contract: fix optimize, add preview -> commit path | - | | S25-02 | Mission schema version, normalization & legacy compatibility | S25-01 | | S25-03 | Safe long-form planning prompt & authorized agent write mechanism | S25-01, S25-02 | | S25-04 | Multi-goal authoring editor & optimized-preview UI | S25-01, S25-02 | | S25-05 | Per-goal `full_prompt` drawer, copy actions & briefing rendering | S25-02 | | S25-06 | Active-mission presentation: one-goal rail & gradient progress | S25-05 | | S25-07 | Mission archive actions & multi-mission management | S25-01, S25-02 | | S25-08 | Claude Code parity, copied-prompt e2e & responsive hardening | S25-03-S25-07 | | S25-09 | Mission Control documentation & end-to-end validation / release | all | Ordering rationale: contracts and storage first (S25-01, S25-02) because every UI affordance writes through them; the safe write mechanism (S25-03) before any UI that triggers agent-authored missions; authoring/preview (S25-04) and per-goal execution affordances (S25-05) next because they are the core product restoration; presentation polish (S25-06) on top of the goal cards it restyles; archive management (S25-07) once the commit/schema paths exist; cross-agent parity and responsive/e2e hardening (S25-08) once the surface is feature complete; documentation and full-phase validation last (S25-09). *** #### S25-01 - Mission Write Contract: Fix Optimize, Add Preview -> Commit Path **Resolves:** Finding #3, Priority 1.1, Endpoint Comparison (optimize row), Suggested Target UX item 3 (contract half). **Reference (v2.3):** `v2.3/vite.config.ts:778-799` (GET `/__hermes_missions` -> bare `{ mission | null }`), `:799-943` (optimize handler - token-gated, shells `hermes`, returns the mission), `:944-1050` (create handler - loopback-only, no token, persists as active: the persistence pattern optimize must adopt for commit), `:1051-1099` (tick), `:1100-1124` (clear). Component side: `v2.3/src/components/hermes-mission-control.tsx:243-249` (endpoint contract comments), `:547-555` (`refetch` GET), `:610-640` (tick/clear fetches). Note: v2.3 `create` persists immediately with no preview step - the preview -> commit split is AI OS-new, layered on top of this endpoint shape to preserve the admin gate. **Objective.** Eliminate the confirmed optimize-write bug and replace ambiguous optimize semantics with an explicit two-step model: optimize returns a non-persisted candidate; a separate authorized commit persists it and sets it active. **Scope (in).** * `scripts/lib/hermes-admin-bridge.ts`: make `handleMissionOptimizeRequest` return an explicit preview envelope (`{ ok: true, preview: true, mission }`) that does not write the store. Add `handleMissionCommitRequest` (`POST /__hermes_missions/commit`) that validates an optimized/authored mission document and persists it as active via `writeMissionStore`, reusing the create validation and ID rules. * `src/lib/hermes-admin-types.ts`: add `HermesMissionCommitRequest`, a `preview` discriminator on the optimize write body, and parsers that reject malformed payloads. * `src/hooks/use-hermes-admin.ts`: split `optimizeMission` (returns preview, never invalidates as if active) from a new `commitMission`; keep mutation state, busy guards, and admin gating. **Scope (out).** No UI rendering of the preview yet (S25-04). No schema version field yet (S25-02). **Build steps.** 1. Reproduce the bug in a failing bridge test (optimize currently reports success without persisting). 2. Implement the preview return + the commit endpoint + path/ID confinement. 3. Wire the admin hook split and update existing optimize call sites to treat the result as a candidate. 4. Update bridge inventory/preflight tests for the new write endpoint. **Exit criteria.** * Optimize never mutates `missions.json`; commit persists and sets active. * Commit requires the full admin preflight; rejected/again-tested when gate is off or token fails. * `hermes-admin-bridge.test.ts`, `hermes-admin-types.test.ts`, and `use-hermes-admin.test.tsx` cover preview-vs-commit, persistence, and rejection paths and pass. *** #### S25-02 - Mission Schema Version, Normalization & Legacy Compatibility **Resolves:** Priority 2.5, Priority 3.8, Finding #7, Mission Data Contract, Testing Comparison (legacy coverage). **Reference (v2.3):** `v2.3/src/components/hermes-mission-control.tsx:265-286` (`Actor`, `Status = "queued" | "active" | "done"`, `MiniGoal`, `Mission` - note `done_when`/`full_prompt` are optional and there is **no** `schema_version`), `v2.3/vite.config.ts:751` (`MISSIONS_FILE` = `~/.hermes/missions.json`), `:778-799` (GET returns the bare `{ mission }` endpoint envelope). The legacy permutations to normalize are exactly the gaps between the loose v2.3 mission file entries and the AI OS typed contract; v2.3 has no schema-version or normalization layer, so that hardening is AI OS-new over the v2.3 on-disk `{ active, missions }` shape. **Objective.** Version the mission document and make the read path robust to legacy/malformed/v2.3-shaped data so existing `~/.hermes/missions.json` files load cleanly and future storage migrations are safe. **Scope (in).** * Add a `schema_version` field to the mission document (write it on create and commit; default/upgrade it on read). * `scripts/lib/hermes-dev-bridge.ts`: harden `normalizeMission` / `normalizeMissionGoal` for missing `full_prompt`, missing `estimate`, unknown status (-> `queued`), active-pointer mismatch, malformed mission entries, and archived (non-active) mission lists. * `src/lib/hermes-types.ts`: surface `schema_version` and keep the richer envelope (`ok`, `active`, `mission`, `total`, `missions`). * Document the raw v2.3 endpoint incompatibility (envelope vs `{ mission }`) in the bridge and in the data contract notes. **Scope (out).** No UI changes; no new endpoints. **Build steps.** 1. Add the version field + migration-on-read (legacy docs without a version are upgraded in memory; persisted on next write). 2. Expand normalization branches and fixtures for every legacy case listed. 3. Add compatibility tests covering each malformed/legacy permutation. **Exit criteria.** * A v2.3-shaped `missions.json` (no version, `{ active, missions }` store, optional fields, mixed statuses) loads without throwing and renders a valid summary. * `hermes-dev-bridge.test.ts` and `hermes-types.test.ts` cover all six legacy permutations and pass. *** #### S25-03 - Safe Long-Form Planning Prompt & Authorized Agent Write Mechanism **Resolves:** Priority 1.3, Finding #6, Security Tradeoff, Appendix A, Endpoint Comparison (create row). **Reference (v2.3):** the planning prompt is ported directly from `v2.3/src/components/hermes-mission-control.tsx:313-509` (`LONG_PROMPT_BODY`) --- specifically the framing/guardrails (313-329), mission rubric (330-336), actor "session boundary" rule (336-385), discovery (404-422), silent multi-pass decomposition (424-429), the `full_prompt` spec (431-456) with the literal `/goal` prefix rule (435-437) and the 8-section human briefing (445-456), and Step 4 (458-509). `buildLongPrompt(agent)` (511-523) is the per-agent self-address pattern to mirror; `EmptyPanel`/`copy()`/Copy-prompt button (783-944) is the copy-to-clipboard surface. Critically, Step 4's tokenless `curl ... /__hermes_missions/create` (462) and the "No token required --- loopback-only is the security boundary" comment at `v2.3/vite.config.ts:944-951` are exactly what this session replaces: re-point Step 4 at the AI OS admin-gated commit path. The authorized short-lived-snippet mechanism is AI OS-new. **Objective.** Restore the v2.3 planning-prompt depth (Appendix A) as copyable, AI-OS-safe operator copy, and provide a write mechanism that lets an agent-authored mission reach the store without weakening the admin gate. **Scope (in).** * Author the long-form planning prompt for both agent presentations: framing guardrails, mission rubric, the actor "session boundary" rule, mandatory discovery, silent multi-pass decomposition, and the `full_prompt` spec - per Appendix A - with Step 4 re-pointed away from the tokenless curl. * Implement the safe write path: a browser-generated, short-lived authorized curl snippet that embeds the same-run token and expires with the dev server, AND/OR an admin-chat -> mission-JSON -> `commitMission` flow that persists through the already-authorized hook (reusing S25-01 commit). * Token/snippet handling: scoping, expiry, and redaction in any displayed command; never echo the token into logs or error surfaces. **Scope (out).** The multi-goal manual editor (S25-04). Per-card copy of individual goals (S25-05). **Build steps.** 1. Encode the Appendix A prompt as versioned constants keyed by agent, with Step 4 describing the authorized AI OS path instead of `localhost:8081` tokenless create. 2. Implement the chosen safe write mechanism end to end against the S25-01 commit endpoint. 3. Add tests for snippet generation, token expiry/scoping, redaction, and the admin-chat -> commit happy path and rejection paths. **Exit criteria.** * Copying the prompt yields a complete planning contract that never instructs a tokenless POST. * An agent-authored mission can be committed only through an admin-gated path; expired/unauthorized snippets are rejected and tested. * The admin gate is provably unchanged in strength. *** #### S25-04 - Multi-Goal Authoring Editor & Optimized-Preview UI **Resolves:** Finding #5, Priority 2.4, Suggested Target UX items 2-3, Executive Summary (one-goal form gap). **Reference (v2.3):** the *field set and limits* the editor must capture come from the payload schema in `v2.3/src/components/hermes-mission-control.tsx:462-489` (title, `binary_outcome` <=12 words, `deadline_days` 7-42, `mini_goals[]` with `num`/`title` <=5 words/`actor`/`done_when` <=8 words/`full_prompt`) and the `MiniGoal`/`Mission` types (268-286). Note: v2.3 authors missions **only** through the prompt -> curl flow - it has **no manual multi-goal editor and no optimized-preview state**, so the editor UI and the preview -> "Set active" commit step are AI OS-new; v2.3 is the reference for the data they produce, not for the controls. **Objective.** Replace the single-human-goal create form with a real authoring editor and render the optimized candidate as a preview that requires an explicit commit. **Scope (in).** * `src/components/hermes/hermes-mission-control.tsx`: dynamic mini-goal rows with add/remove; per-goal actor selection (`hermes`/`human`), `done_when`, `estimate`, and optional `full_prompt`; min/max goal counts aligned to the post-S25-02 admin contract; validation messages. * Two modes: "manual lightweight" and "optimized from prompt", kept visually separated so the panel does not become dense. * Optimized-preview state: show proposed title, binary outcome, deadline, actor split, and mini-goals; a "Set active mission" action calls `commitMission` (S25-01); a discard action drops the candidate. * Empty state offers the three actions: copy planning prompt (S25-03), optimize from prompt, create manually. **Scope (out).** Per-goal `full_prompt` drawer/copy on the active card (S25-05). Rail/gradient presentation (S25-06). **Build steps.** 1. Build the dynamic editor + validation aligned to the finalized mission contract limits. 2. Build the preview renderer fed by the S25-01 optimize result. 3. Wire commit/discard; refresh via query invalidation only. **Exit criteria.** * An operator can author a multi-goal mission with mixed actors and optional `full_prompt`, and can promote an optimized candidate via explicit commit. * Optimize now visibly changes Mission Control state (preview -> commit -> active). * Component tests cover add/remove, actor selection, validation bounds, preview render, commit, and discard. *** #### S25-05 - Per-Goal `full_prompt` Drawer, Copy Actions & Briefing Rendering **Resolves:** Finding #4, Priority 1.2, AI OS Product Regressions #1 and #5, UX Comparison (per-card copy, `buildCopyText`, `formatHumanBrief`). **Reference (v2.3):** port directly from `v2.3/src/components/hermes-mission-control.tsx` - `buildCopyText` (1074-1128), including the `/goal` safety net that forces the prefix onto agent cards (1087-1106); `formatHumanBrief` + `HUMAN_BRIEF_LABELS` (1130-1196) for the 8-section human-briefing render with prose fallback; `BriefingDrawer` (1209-1577) for the no-layout-shift overlay, the `humanBlocks` split (1273), the "Copy /goal prompt" button (1532), and the long-prompt overflow/scroll handling (1276-1320); `estimateToPips` (1035-1073). The authored-content rules these mirror live in the prompt's `full_prompt` spec (431-456). **Objective.** Make mini-goal cards actionable: surface `full_prompt`, render human briefings structurally, and provide per-card copy that bridges planning to execution. **Scope (in).** * Expandable detail drawer/modal on `GoalCard` showing `full_prompt` with strong wrapping and bounded height; the page underneath must not shift. * Copy behavior: agent (`hermes`) goals -> "Copy /goal prompt" with `/goal` prefix validation (warn or correct if missing); human goals -> "Copy briefing". * A `buildCopyText` equivalent shared by card button and drawer, including the guard line preventing self-ticking of the Mission Control card. * A `formatHumanBrief` equivalent that renders the 8-section human briefing into labeled sections, falling back to prose when unstructured. **Scope (out).** The one-goal rail and gradient bar (S25-06). **Build steps.** 1. Add the drawer/modal + `full_prompt` rendering. 2. Implement copy text builders + prefix validation. 3. Implement structured briefing formatting with graceful fallback. **Exit criteria.** * Every mini-goal exposes its `full_prompt`; agent cards copy a valid `/goal` -prefixed prompt; human cards copy a readable briefing. * Component tests cover drawer open/close, prefix validation/warning, copy output for both actors, and structured vs prose briefings. *** #### S25-06 - Active-Mission Presentation: One-Goal Rail & Gradient Progress **Resolves:** UX Comparison (richer active presentation), AI OS Product Regression on visual hierarchy, Suggested Target UX item 4. **Reference (v2.3):** port from `v2.3/src/components/hermes-mission-control.tsx` - `MissionGoalRail` (1583-1987) for the one-goal-at-a-time rail, `activeGoalId` state (1615), keyboard navigation (1635-1660), and scroll-to-active behavior (1669+); the progress bar with per-goal milestone ticks (1731-1808, gradient at 1767); the exact-decimal fill geometry comment and math (561-569) that aligns the fill under the current milestone; `MissionBody` mounting the rail (945-1034, mount at 1009); the fixed-height stage that hosts rail-or-briefing in the same slot (1889-1976) and the rail scrollbar CSS (1981-1987). **Objective.** Bring the active-mission view up to v2.3's execution feel without abandoning the AI OS component discipline. **Scope (in).** * One-goal-at-a-time rail/focus over the active mini-goal while keeping the full grid available. * Flowing-gradient progress bar whose fill geometry uses the exact decimal so the fill ends precisely under the current goal's milestone tick; rounding only at the label. * Stronger visual hierarchy: estimates, actor pills, status, and the existing reduced-motion-gated confetti preserved. **Scope (out).** No contract changes; presentation only. **Build steps.** 1. Add the rail/focus interaction layered on the S25-05 cards. 2. Implement the precise gradient/milestone geometry. 3. Tune hierarchy and verify reduced-motion behavior. **Exit criteria.** * Active mission reads as an execution surface: clear current goal, accurate milestone-aligned progress, strong hierarchy. * Component tests cover progress geometry at representative completion ratios and rail navigation; reduced-motion path verified. *** #### S25-07 - Mission Archive Actions & Multi-Mission Management **Resolves:** Priority 3.7, Suggested Target UX item 5, Mission Data Contract (archive list). **Reference (v2.3): none - AI OS-new.** v2.3 tracks a single active mission only: `create` (`v2.3/vite.config.ts:944-1050`) replaces whatever was active and `clear` (`:1100-1124`) drops it; there is no archive, list, or reactivate path, and the component never renders inactive missions. The substrate for this session is the AI OS-side mission list already produced by the read bridge (`scripts/lib/hermes-dev-bridge.ts` envelope `missions[]`) and the commit/active-pointer path from S25-01. **Objective.** Make the existing mission list actionable so old missions can be reactivated or set active. **Scope (in).** * Archive list actions: "Set active" / "Reactivate" persisting through an admin-gated write (reusing/extending the S25-01 commit/active path); ensure active-pointer integrity when switching. * Guard against switching while a write is in flight; explicit confirmation when replacing a different active mission. **Scope (out).** Bulk operations beyond set-active/reactivate. **Build steps.** 1. Add an authorized set-active endpoint or reuse commit with an existing-ID path; validate the target exists. 2. Wire archive-list actions + confirmation + busy guards. 3. Test pointer integrity and rejection under a closed admin gate. **Exit criteria.** * An operator can reactivate any archived mission; the active pointer stays consistent and tested. * Component + bridge tests cover set-active, pointer mismatch, and gated rejection. *** #### S25-08 - Claude Code Parity, Copied-Prompt E2E & Responsive Hardening **Resolves:** Finding #9, Priority 2.6, AI OS Strengths (no-overflow), Suggested Target UX (full assembly), `claude-code-mission-page.tsx` parity. **Reference (v2.3):** the parity model to mirror is `v2.3/src/components/hermes-mission-control.tsx:515-532` - `buildLongPrompt(agent)` and the `MissionControlAgent`/`agent`-prop mechanism that swaps only presentation copy ("Paste to Hermes" / "Paste to Claude Code" / neutral) while the mission body stays agent-agnostic. The overflow/wrapping behavior to match for copied prompts is the `BriefingDrawer` long-`/goal`-prompt scroll handling (`:1276-1320`) and the `mission-rail` scroll CSS (`:1981-1987`). Note: v2.3 ships **no tests**, so the e2e/responsive coverage itself is AI OS-new. **Objective.** Guarantee every new affordance works identically for the `claude-code` presentation and that copied prompts/briefings are responsive and overflow-safe. **Scope (in).** * Verify/extend `claude-code` presentation and `claude-code-mission-page.tsx` so authoring, preview/commit, per-goal copy, drawer, rail, and archive all render with correct agent copy and identical contracts. * Route/e2e coverage for copied prompts: no horizontal overflow, long-text wrapping, and mobile drawer behavior across both agents. * Assemble and verify the full Suggested Target UX layout (header -> empty/3 actions -> optimized preview -> active mission -> archive). **Scope (out).** New features; this session hardens existing ones. **Build steps.** 1. Sweep both agent presentations for parity and fix copy/contract drift. 2. Add Playwright/e2e specs for overflow, wrapping, and mobile drawer. 3. Validate the assembled layout end to end in both routes. **Exit criteria.** * `hermes` and `claude-code` routes are at feature parity. * `tests/e2e/hermes-agent.spec.ts` (and a Claude Code counterpart) assert no overflow, correct wrapping, and working mobile drawer, and pass. *** #### S25-09 - Mission Control Documentation & End-to-End Validation / Release **Resolves:** Priority 3.9, Finding #7 (documentation half), Testing Comparison (full envelope), Bottom Line (activation). **Reference (v2.3):** `v2.3/README.md` and `v2.3/CHANGELOG.md` for the original Mission Control product framing and intent to reconcile against the shipped AI OS contract; the endpoint contract comments at `v2.3/src/components/hermes-mission-control.tsx:243-249` and the `v2.3/vite.config.ts` mission handlers (778-1124) as the behavioral baseline the new docs supersede. Note: v2.3 has no contract/API doc or test suite, so the documentation and validation envelope are AI OS-new. **Objective.** Document the final contract and certify the whole surface. **Scope (in).** * Document the final Mission Control contract, endpoints (including `/__hermes_missions/commit` and any set-active path), schema version, and the safe write mechanism in `docs/agent-pages.md`, `docs/data-contract.md`, and `docs/api/README_api.md`. * Carry forward lessons into `.spec_system/CONSIDERATIONS.md` and update `.spec_system/SECURITY-COMPLIANCE.md` for the new write surface. * Full validation pass: complete test suite green; all ten UI states verified; demo/live parity; accessibility; a security review of the new write/commit endpoints and the authorized-snippet mechanism. **Scope (out).** New functionality. **Build steps.** 1. Write/refresh the contract docs and cross-surface references. 2. Run and green the full suite + accessibility + security review. 3. Certify the phase outcome. **Exit criteria.** * Docs describe the activated Mission Control loop accurately and match the shipped contracts. * The full suite passes; the admin gate is verified intact; the phase binary outcome is YES. *** #### Coverage Traceability Every actionable item in this document maps to a session: | Source item | Session | | --------------------------------------------------------------------------- | --------------------------------------------------------- | | Finding #3 / Priority 1.1 - optimize semantics | S25-01 | | Endpoint Comparison - optimize persistence | S25-01 | | Suggested Target UX item 3 - preview -> "Set active" | S25-01 (contract), S25-04 (UI) | | Priority 3.8 - mission schema version | S25-02 | | Priority 2.5 - legacy mission compatibility tests | S25-02 | | Finding #7 - contract/compatibility drift + documentation | S25-02 (compat), S25-09 (docs) | | Mission Data Contract - normalization of legacy/malformed files | S25-02 | | Priority 1.3 - safe long-form planning prompt | S25-03 | | Appendix A - full planning-prompt anatomy | S25-03 | | Finding #6 / Security Tradeoff - safe agent write mechanism | S25-03 | | Finding #5 / Priority 2.4 - multi-goal authoring editor | S25-04 | | Suggested Target UX item 2 - empty state, three actions | S25-04 | | Finding #4 / Priority 1.2 - `full_prompt` visibility + copy | S25-05 | | Product Regression #1 - `full_prompt` on cards | S25-05 | | Product Regression #5 - per-card `/goal` copy | S25-05 | | UX Comparison - `buildCopyText`, `formatHumanBrief`, briefing overlay | S25-05 | | UX Comparison - one-goal rail, gradient progress, hierarchy | S25-06 | | Suggested Target UX item 4 - active mission view | S25-05, S25-06 | | Priority 3.7 - mission archive actions | S25-07 | | Suggested Target UX item 5 - archive list set-active/reactivate | S25-07 | | Finding #9 - multi-agent parity preserved | S25-08 (+ all UI sessions) | | Priority 2.6 - route/e2e for copied prompts | S25-08 | | AI OS Strengths - no overflow / wrapping / mobile drawer | S25-08 | | Priority 3.9 - final contract documentation | S25-09 | | AI OS Strengths + Safety Comparison - no regression of gate/state/contracts | Cross-cutting guardrails (all sessions), certified S25-09 | #### Definition of "Fully Activated" The phase is complete only when all of the following are true: 1. Optimize produces a preview; commit persists and activates it; manual create still persists. No silent-success path remains. 2. Mission documents are versioned; legacy/v2.3-shaped files load and normalize cleanly. 3. The long-form planning prompt is restored for both agents and never instructs a tokenless write; an authorized write mechanism exists. 4. Missions can be authored with multiple mixed-actor mini-goals and optional `full_prompt`, manually or via optimize-then-commit. 5. Every mini-goal exposes `full_prompt`; agent cards copy a valid `/goal` prompt; human cards copy a structured briefing. 6. The active mission renders as an execution surface (rail, milestone-accurate progress, hierarchy). 7. Archived missions can be reactivated/set active with pointer integrity. 8. `hermes` and `claude-code` routes are at parity; copied prompts are overflow-safe and mobile-correct. 9. Contracts and the safe write surface are documented; the full test suite, accessibility, and a security review pass; the admin gate is verified intact. --- # 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_25/prd_phase_25.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.