> 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/sessions/phase40-session13-command-ux-and-slash-actions/spec.md).

# Session Specification

**Session ID**: `phase40-session13-command-ux-and-slash-actions` **Phase**: 40 - Claude OS v2.10.1 Semantic Port **Status**: Complete **Created**: 2026-07-03 **Base Commit**: 2244ea893bdb1092eb8c508fc7e26d113c70d1ba

***

## 1. Session Overview

This session adds the visible Hermes command surface on top of the already shipped admin command endpoint and compact chat flow. It gives local AI OS users a split command menu plus slash actions for compact, insights, status, doctor, version, update, and new chat without treating slash text as a normal model prompt.

This is the next executable Phase 40 session because the analyzer reports sessions 1 through 12 complete. Session 05 provides the token/admin-gated `runCommand` hook, Session 11 provides the composer toolbar placement, and Session 12 provides the compact flow that `/compact` should call.

The work stays inside the existing split AI OS Hermes chat owners. The browser UI should call the allowlisted admin command contract, render redacted command output as a controlled Hermes message, and preserve the Session 04 rule that sanitized `info` SSE events do not become normal assistant reply text.

***

## 2. Objectives

1. Add a split command menu and slash action model for the existing Hermes chat composer.
2. Route command actions through `useHermesAdmin().commands.runCommand` and existing local chat actions instead of prompt text.
3. Render redacted command success and failure output as stable Hermes messages with preformatted monospace content.
4. Require explicit confirmation before update and show timeout/admin/write-gate failures clearly.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase40-session05-command-endpoint` - The `/__hermes_cmd` bridge route, command parser, sanitizer, and `useHermesAdmin().commands.runCommand` action are available.
* [x] `phase40-session11-chat-model-selector-and-context-meter` - The composer toolbar has placement for compact controls and additional chat actions.
* [x] `phase40-session12-compact-and-chat-polish` - Compact chat behavior, carryover state, reply copy, and startup-warning filtering are available.

### Required Tools Or Knowledge

* Existing Hermes chat components under `src/components/hermes/chat/`.
* Existing admin command response types in `src/lib/hermes-admin-types.ts`.
* React 19 component state and accessible menu/listbox patterns.
* Vitest, Testing Library, and happy-dom interaction tests.

### Environment Requirements

* Repository dependencies installed with the pinned Bun version.
* No live Hermes credentials are required for component and helper tests.
* Live command execution remains local-only, admin-gated, and token-gated.

***

## 4. Scope

### In Scope (MVP)

* AI OS chat users can open a split command menu from the composer - Implement the menu as a product action surface backed by a fixed local action registry.
* AI OS chat users can type slash actions for compact, insights, status, doctor, version, update, and new chat - Filter and execute known actions without sending the slash text to Hermes as a prompt.
* AI OS chat users can run Hermes status, doctor, version, insights, and update - Route only to the existing `HermesCommandName` allowlist through `useHermesAdmin().commands.runCommand`.
* AI OS chat users can inspect command output safely - Show redacted stdout/stderr, exit code, and controlled failure state in a stable pre/monospace assistant bubble.
* AI OS chat users must confirm update before it runs - Provide cancel and accept paths and pass the required `confirmation: "update"` request only after confirmation.
* AI OS chat users see sanitized runtime diagnostics in the right place - Preserve chat `info` SSE events as Intelligence activity or non-transcript diagnostics, not assistant reply text.
* Product surfaces remain discoverable without tutorial prose - Use menu labels, input hints, affordances, and concise status text instead of in-app instructions.

### Out Of Scope (Deferred)

* Adding new Hermes command endpoint capabilities beyond the existing allowlist - Reason: Session 05 owns the command endpoint and this session is UI-only command orchestration.
* Shell-like freeform command execution - Reason: AI OS preserves fixed local command boundaries and does not expose arbitrary shell execution from the browser.
* Ministry UI or MoA save UX - Reason: Sessions 14 and 15 own Ministry builder, analytics, config generation, and save behavior.
* Documentation updates - Reason: Session 17 updates docs after matching command UI behavior ships and tests pass.

***

## 5. Technical Approach

### Architecture

Create a small command action registry near the chat components that maps menu items and slash aliases to either an existing local chat action (`compact`, `new-chat`, `insights` portal) or an admin command request (`status`, `doctor`, `version`, `update`). Keep the registry typed so every admin command maps to `HermesCommandName` and every slash action has one handler path.

Extend `ChatComposer` with a command menu and slash suggestion surface while leaving prompt ownership in `HermesChatTab`. `HermesChatTab` should own execution state because it already has access to prompt state, selected session, compact behavior, write gates, local messages, and the `admin` command hook. Slash submit should execute a command action when the trimmed prompt matches a known slash command; otherwise it remains a normal send.

Render command output through `ChatMessageList` as an assistant-side command message. Command content should use visible, redacted `stdout` and `stderr` from the bridge response, include bounded status labels, and use a preformatted monospace block that wraps without shifting the layout. Failed or timed-out commands should use the hook mutation error and command context to append a controlled failure message without exposing private paths or raw request bodies.

### Design Patterns

* Fixed action registry: keep menu and slash behavior generated from one typed command/action list.
* Existing admin boundary: reuse `useHermesAdmin().commands.runCommand` and do not add bridge routes.
* Duplicate-trigger prevention: block repeated command, compact, update, and send actions while any relevant action is in flight.
* Product-only copy: labels and failures describe local command state without raw debug text, private paths, prompt bodies, or credentials.
* Scoped lifecycle cleanup: clear armed slash/update state on prompt change, reset, new chat, session selection, demo/live changes, and command completion.

***

## 6. Deliverables

### Files To Create

| File                                                           | Purpose                                                                                                  | Est. Lines |
| -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | ---------- |
| `src/components/hermes/chat/command-actions.ts`                | Typed command/slash registry, filtering, request builders, and output formatting helpers.                | \~180      |
| `src/components/hermes/chat/command-menu.tsx`                  | Split command menu and slash suggestion UI for the Hermes composer.                                      | \~220      |
| `src/components/hermes/chat/__tests__/command-actions.test.ts` | Focused helper coverage for action lookup, slash filtering, request construction, and output formatting. | \~180      |

### Files To Modify

| File                                                            | Changes                                                                                                                              | Est. Lines |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
| `src/components/hermes/chat/hermes-chat-tab.tsx`                | Wire command execution, slash routing, update confirmation, command local messages, duplicate prevention, and cleanup.               | \~260      |
| `src/components/hermes/chat/chat-composer.tsx`                  | Add command menu slot, slash suggestion rendering, slash submit routing, and stable command status copy.                             | \~170      |
| `src/components/hermes/chat/chat-message-list.tsx`              | Render command output/error bubbles with preformatted monospace content, bounded copy, and accessible labels.                        | \~150      |
| `src/components/hermes/chat/chat-types.ts`                      | Extend local chat message metadata for command messages and any small shared command rendering types.                                | \~80       |
| `src/components/hermes/chat/index.ts`                           | Export command helpers or types required by tests and route consumers.                                                               | \~20       |
| `src/components/hermes/chat/__tests__/hermes-chat-tab.test.tsx` | Cover menu execution, slash execution, update confirm/cancel, compact/new chat routing, command failures, and info event boundaries. | \~360      |
| `src/lib/__tests__/hermes-intelligence-events.test.ts`          | Preserve proof that `info` events map to Intelligence activity without assistant transcript text.                                    | \~40       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] The command menu exposes compact, insights, status, doctor, version, update, and new chat as fixed actions.
* [ ] Slash actions filter from the current draft and execute known actions without sending slash text as a Hermes prompt.
* [ ] Status, doctor, version, insights, and update call `admin.commands.runCommand` with allowlisted command names only.
* [ ] Update requires explicit confirmation and supports both cancel and accept paths.
* [ ] Command success output appears as a redacted Hermes assistant message with stdout/stderr preserved in stable preformatted monospace blocks.
* [ ] Command timeout, admin-disabled, token, offline, and endpoint failures produce controlled product-facing error messages.
* [ ] `/compact` calls the existing compact flow and respects compact disabled/pending states.
* [ ] `/new-chat` starts a fresh chat and clears stale command, slash, and confirmation state.
* [ ] Sanitized chat `info` SSE events remain out of normal assistant reply text and continue mapping to Intelligence activity.

### Testing Requirements

* [ ] Helper tests cover slash lookup, filtering order, aliases, command request generation, and command output formatting.
* [ ] Component tests cover command menu execution, slash execution, command output rendering, command error rendering, and duplicate-trigger prevention.
* [ ] Component tests cover update cancel and update confirm request payloads.
* [ ] Component tests cover `/compact`, `/new-chat`, and known slash text not being sent through `chat.sendPrompt`.
* [ ] Existing model selector, context meter, compact, image upload, reply copy, and send tests remain compatible.

### Non-Functional Requirements

* [ ] The command menu and slash suggestions have stable dimensions and do not overlap composer controls on mobile or desktop.
* [ ] Interactive controls include accessible labels, keyboard navigation, and focus management.
* [ ] Browser-facing UI exposes only safe labels, redacted command output, and visible reply text.
* [ ] No generated private data, raw home paths, auth JSON paths, API keys, tokens, account IDs, raw prompts, or raw bridge diagnostics are introduced.

### Quality Gates

* [ ] All files ASCII-encoded.
* [ ] Unix LF line endings.
* [ ] Code follows project conventions.
* [ ] Primary user-facing surfaces contain product-facing copy only.

***

## 8. Implementation Notes

### Working Assumptions

* A local chat command message is the right output surface for command results: the session requires output to appear as a redacted Hermes message, and `ChatMessageList` already owns assistant-side bubble rendering and reply copy boundaries.
* Slash action discovery should be registry-driven rather than hard-coded inside the composer: one registry lets menu labels, aliases, disabled copy, command payloads, and tests stay aligned.
* The `insights` slash action should open Hermes Intelligence when the launcher prop exists and otherwise fall back to the existing `insights` admin command: the session names `insights` alongside command actions, while the current chat tab already has an optional Intelligence launcher and the command endpoint also allowlists `insights`.
* Documentation remains deferred to Session 17: the Phase 40 PRD says docs must describe shipped AI OS behavior only after implementation and tests exist.

### Conflict Resolutions

* Session 13 asks for "insights" as a slash action, while Session 04 already maps chat `info` events to Intelligence activity and the command endpoint allowlists `insights --days 30`. The selected interpretation is to support both product-available paths from one action: prefer opening the existing Intelligence surface when available, and use the allowlisted command when executing a command action is the selected behavior or no launcher is present.
* The upstream phrase "slash actions" could imply freeform command text, but the Phase 40 PRD, Session 05 command endpoint, and security considerations all favor fixed allowlisted commands. This plan implements fixed actions only.

### Key Considerations

* Do not add shell-style freeform entry or pass arbitrary prompt text to `/__hermes_cmd`.
* Keep command output bounded by the bridge response and never reintroduce raw paths, account IDs, auth filenames, token-shaped strings, or private prompt bodies.
* Keep demo mode read-only: menu and slash items may be visible, but write actions must surface gated copy instead of running local commands.
* Preserve compact carryover isolation from Session 12 when `/compact` runs through the slash action.
* Avoid crowding the Session 11 selector/context toolbar; command menu placement belongs in the composer action area or as a compact split control.

### Potential Challenges

* Slash suggestion state can conflict with normal prompt composition; treat only a trimmed draft beginning with `/` as a candidate action and clear action state when the draft no longer matches.
* Command failures currently return through mutation errors rather than success bodies; capture the selected action context before calling `runCommand` so failure messages can still name the attempted action safely.
* Update confirmation can be accidentally skipped if menu selection executes immediately; model update as an armed state that requires a second explicit confirm action.
* Preformatted command output can overflow narrow screens; wrap long lines and bound max height with scroll inside the bubble.

### Relevant Considerations

* \[P38] **Upstream ports are semantic, not wholesale**: Translate command UX into existing AI OS chat owners instead of copying upstream route or middleware files.
* \[P38] **Local control-plane gates are defense in depth**: Preserve loopback, Host-header, token/admin, schema, timeout, and safe-error behavior by reusing the existing admin command endpoint.
* \[P21] **Do not let token-shaped strings or auth headers reach browser state or logs**: Keep command output redacted and never surface credential-shaped payloads.
* \[P31-P39] **Public-demo, AI Rogue, and hosted-surface gates stay bundled**: Demo/public behavior must remain read-only and must not call local write bridges.
* \[P00] **Stack conventions**: Stay within Bun, Vite 8, TanStack Start, React 19, Radix UI, and local component conventions.

### Behavioral Quality Focus

Checklist active: Yes Top behavioral risks for this session:

* A slash command could be sent as prompt text instead of executing the intended fixed action.
* A command or update action could run twice from rapid clicks, Enter key repeats, or menu plus slash overlap.
* Command output or error copy could leak raw private paths, auth filenames, account identifiers, tokens, or bridge diagnostics.

***

## 9. Testing Strategy

### Unit Tests

* Test command action registry lookup, slash aliases, filtering priority, disabled state derivation, update confirmation request payloads, and command output formatting in `src/components/hermes/chat/__tests__/command-actions.test.ts`.
* Extend Intelligence event tests to prove `info` events remain diagnostic activity and not assistant transcript turns.

### Integration Tests

* Extend `src/components/hermes/chat/__tests__/hermes-chat-tab.test.tsx` for menu execution, slash execution, update cancel/accept, command success messages, command failure messages, duplicate-trigger prevention, `/compact` routing, `/new-chat` routing, and write-gate behavior.
* Preserve existing tests for model selector, context meter, compact, image upload, reply copy, warning filtering, grounding, and ordinary prompt sending.

### Runtime Verification

* Run focused Vitest coverage for command helpers, Hermes chat tab, admin hook, admin types, and Intelligence event mapping.
* Spot-check the Hermes chat composer in live dev mode for desktop and mobile widths if implementation changes visual layout materially.

### Edge Cases

* Unknown slash text remains a normal prompt only when the user submits intentionally and does not match a fixed action.
* `/update` arms confirmation, cancel clears it, and accept calls `runCommand({ command: "update", confirmation: "update" })` once.
* Offline, token missing, admin disabled, endpoint error, timeout, and non-zero command failure all render bounded product-facing failures.
* Empty stdout/stderr still renders a useful command completion message.
* Long command output wraps or scrolls without resizing surrounding composer controls.
* Demo mode cannot execute admin commands and does not call the local bridge.

***

## 10. Dependencies

### Other Sessions

* Depends on: `phase40-session05-command-endpoint`, `phase40-session11-chat-model-selector-and-context-meter`, `phase40-session12-compact-and-chat-polish`
* Depended by: `phase40-session17-docs-metadata-and-gitignore-closeout`, `phase40-session18-full-validation-and-handoff`
* Related but independent later work: `phase40-session14-ministry-builder-and-pantheon`, `phase40-session15-ministry-config-analytics-and-save-ux`

***

## Next Steps

Run the `implement` workflow step to begin implementation.


---

# 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/sessions/phase40-session13-command-ux-and-slash-actions/spec.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.