> 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/phase26-session06-ingest-ui-connect-prompt-starter-chips/spec.md). # Session Specification **Session ID**: `phase26-session06-ingest-ui-connect-prompt-starter-chips` **Phase**: 26 - Knowledge Graph Shared Brain Port **Status**: Complete **Created**: 2026-06-09 *** ## 1. Session Overview This session activates the operator-facing write affordances on the Knowledge Graph page. Sessions 01-05 already provided graph contracts, seed/demo data, read and admin bridges, the reusable 3D renderer, the read hook, the route shell, the project gallery, the side rail, and sidebar navigation. Session 06 adds the admin-gated ingest UI, the safe connect-with-Hermes prompt, starter-question chips, and a reusable mini stat component. The key boundary is that browser UI may initiate graph ingest and removal only through the existing Knowledge Graph admin hook and the dev-server token endpoint. The component layer must not add ad hoc fetches to `__graphify_ingest` or `__graphify_remove`, must keep demo/admin-disabled/offline/token-failure states explicit, and must prevent duplicate write triggers while requests are in flight. This session deliberately stops before grounded Hermes chat integration. Starter chips dispatch the established `hermes-chat-prefill` browser event and may scroll toward the future chat anchor, but Session 07 owns seed context, Hermes chat props, toolsets, yolo forwarding, and the graphify skill. *** ## 2. Objectives 1. Add a token-aware Knowledge Graph admin UI path that fetches `/__token` and passes the token into `useKnowledgeGraphAdmin` without exposing token values in rendered output, logs, or copied text. 2. Build an `IngestCard` for local paths and Git/GitHub URLs with admin-disabled, demo, offline, token-failure, graphify-missing, busy, success, error, and remove states. 3. Build a copyable connect-with-Hermes prompt that points Hermes at the graph registry and AI OS UI-mediated ingest path without tokenless write, curl, header, or raw token instructions. 4. Add starter-question chips that dispatch `hermes-chat-prefill`, preserve page state, and prepare the surface for Session 07 grounded chat. *** ## 3. Prerequisites ### Required Sessions * [x] `phase26-session03-graph-ingest-removal-admin-bridge` - Provides `/__graphify_admin_status`, `/__graphify_ingest`, `/__graphify_remove`, admin response parsers, `useKnowledgeGraphAdmin`, duplicate write prevention, and graph-list invalidation. * [x] `phase26-session05-read-hook-route-shell-project-gallery` - Provides `/knowledge-graph`, `useKnowledgeGraph`, the page adapter, gallery, side rail, and active project state that hosts this session's UI. ### Required Tools/Knowledge * Bun 1.3.14, React 19, TypeScript, TanStack Query, Tailwind CSS 4, Vitest, and Testing Library. * Existing patterns in `src/hooks/use-knowledge-graph-admin.ts`, `src/lib/knowledge-graph-admin-types.ts`, `src/lib/use-aggregate-refresh.ts`, `src/extensions/trend-finder/hooks/use-trend-finder-run.ts`, and Hermes copy/prompt tests. * Claude OS v2.4 reference route at `/home/aiwithapex/projects/claudeos/claude-os-v2.4/src/routes/codegraph.tsx`, used for behavior only. ### Environment Requirements * Local Vite dev server can serve `/__token` and the Knowledge Graph bridges. * Live ingest remains optional. The UI must remain useful when `graphify` is missing or admin mode is disabled. * Admin writes require loopback, per-run token, `HERMES_DASHBOARD_ADMIN=1`, non-demo UI mode, and hook-mediated browser path. *** ## 4. Scope ### In Scope (MVP) * Operator can request the per-run dev token through a focused hook - parse `/__token`, surface token failure without rendering the token, and abort/reset safely on unmount or re-entry. * Operator can ingest a local path or Git/GitHub URL from the Knowledge Graph page - submit through `useKnowledgeGraphAdmin().ingest` with duplicate-trigger prevention while in flight. * Operator can remove the active graph entry from the Knowledge Graph page - submit through `useKnowledgeGraphAdmin().remove` with active-project revalidation, disabled-while-pending behavior, and clear success/error feedback. * Operator can copy a safe connect-with-Hermes prompt - generate a prompt from the active registry path that contains no tokenless write instruction, no raw token/header text, no `curl`, and no direct bridge mutation instructions. * Operator can click starter-question chips - dispatch `hermes-chat-prefill` with accessible buttons, deterministic chip text, and state preserved on repeated clicks. * Operator can reuse compact stat tiles in the gallery and side rail - add a stable mini stat component with bounded text, tabular numbers, and no layout shift. ### Out of Scope (Deferred) * Hermes chat rendering on `/knowledge-graph` - *Reason: Session 07 owns grounded chat, seed context, toolsets, yolo forwarding, and the graphify skill.* * Homepage Knowledge Graph section and Shared Brain scripts - *Reason: Session 08 owns homepage and script parity.* * Changes to admin bridge security behavior - *Reason: Session 03 already owns endpoint policy; this session consumes it through the hook.* * Final docs, release validation, and end-to-end parity sign-off - *Reason: Session 09 owns closeout.* *** ## 5. Technical Approach ### Architecture Add `useKnowledgeGraphToken` as a narrow hook for `/__token`. It should use TanStack Query or the existing hook idiom, parse `{ token: string }`, expose idle/loading/success/error/offline/demo states, avoid rendering the token, and disable token fetches when demo mode or browser/offline state makes writes unavailable. The token value is passed only into `useKnowledgeGraphAdmin`. Add modular components under `src/components/knowledge-graph/`: `KnowledgeGraphIngestCard`, `KnowledgeGraphConnectPrompt`, `KnowledgeGraphStarterChips`, and `KnowledgeGraphMiniStat`. The page adapter composes the existing read view with the token hook and admin hook, then passes view/admin data into the cards. Component code should use the admin hook's `run` methods rather than fetching mutation endpoints directly. Add a pure prompt builder in `src/lib/knowledge-graph-connect-prompt.ts` so prompt safety is testable without rendering. The prompt should teach Hermes to read the registry and graph files, use graphify query/path/explain when available, and tell the operator to use the AI OS Knowledge Graph UI for new repo registration. It must not include token names, headers, `curl`, or a direct unauthenticated write path. ### Design Patterns * Shared admin hook boundary: UI writes go through `useKnowledgeGraphAdmin` only. * Typed degradation over throws: Token, admin, graphify, offline, demo, and bridge errors are explicit view states. * Reopenable form state: Collapsed/expanded ingest state resets or revalidates on re-entry. * Accessibility-first controls: Buttons have labels, focus rings, keyboard behavior, and stable dimensions. * Pure prompt builder: Copy text is generated from typed inputs and safety-tested as data. ### Technology Stack * React 19 and TypeScript. * TanStack Query for token/admin state where appropriate. * Existing Knowledge Graph read/admin hooks and parser contracts. * Tailwind CSS 4 and local component conventions. * Vitest and Testing Library for hook, pure prompt, and component behavior. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ---------- | | `src/hooks/use-knowledge-graph-token.ts` | Token query for `/__token` with typed states, parse guard, offline/demo handling, and abort cleanup | \~130 | | `src/hooks/__tests__/use-knowledge-graph-token.test.tsx` | Token hook tests for success, invalid response, fetch failure, demo/offline disablement, and no rendered token dependency | \~180 | | `src/lib/knowledge-graph-connect-prompt.ts` | Pure prompt builder and starter-question definitions | \~150 | | `src/lib/__tests__/knowledge-graph-connect-prompt.test.ts` | Prompt safety tests for registry path replacement, project wording, and forbidden tokenless-write text | \~140 | | `src/components/knowledge-graph/knowledge-graph-mini-stat.tsx` | Reusable compact stat tile with stable layout and bounded text | \~70 | | `src/components/knowledge-graph/knowledge-graph-ingest-card.tsx` | Admin-gated ingest/remove card using token/admin hook views | \~260 | | `src/components/knowledge-graph/knowledge-graph-connect-prompt.tsx` | Copyable connect prompt card with clipboard fallback and redacted error handling | \~170 | | `src/components/knowledge-graph/knowledge-graph-starter-chips.tsx` | Starter chip row dispatching `hermes-chat-prefill` | \~100 | | `src/components/knowledge-graph/__tests__/knowledge-graph-ingest-card.test.tsx` | Component tests for token, ingest, remove, gating, duplicate prevention, and status copy | \~260 | | `src/components/knowledge-graph/__tests__/knowledge-graph-connect-prompt.test.tsx` | Component tests for expand/copy/fallback/error copy and prompt text safety | \~180 | | `src/components/knowledge-graph/__tests__/knowledge-graph-starter-chips.test.tsx` | Component tests for chip labels, custom event detail, repeated clicks, and focusable controls | \~130 | ### Files to Modify | File | Changes | Est. Lines | | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- | ---------- | | `src/components/knowledge-graph/knowledge-graph-page.tsx` | Compose token/admin hooks, ingest card, connect prompt, starter chips, and refresh handlers | \~80 | | `src/components/knowledge-graph/knowledge-graph-project-gallery.tsx` | Add the ingest card beside project cards and use the mini stat tile where appropriate | \~60 | | `src/components/knowledge-graph/knowledge-graph-side-rail.tsx` | Reuse the mini stat tile for rail metrics without changing read behavior | \~40 | | `src/components/knowledge-graph/__tests__/knowledge-graph-page.test.tsx` | Extend page composition tests for ingest, prompt, and chips integration | \~120 | | `src/hooks/__tests__/use-knowledge-graph-admin.test.tsx` | Add any missing graphify-missing or remove invalidation expectations needed by UI states | \~40 | *** ## 7. Success Criteria ### Functional Requirements * [ ] `/knowledge-graph` renders ingest, connect prompt, and starter chip affordances without regressing the hero, gallery, 3D panel, or side rail. * [ ] Ingest accepts local paths and Git/GitHub URLs only when admin mode is enabled, browser is online, token is available, and demo mode is off. * [ ] Ingest and remove call `useKnowledgeGraphAdmin` mutations only, block duplicate triggers while pending, and reset or revalidate form state on close/re-entry. * [ ] Remove sends the active graph id through `DELETE /__graphify_remove?id=` via the admin hook and refreshes the registry after success. * [ ] Demo, admin-disabled, offline, token-failure, graphify-missing, busy, success, and error states are visible without exposing private token values or raw command output. * [ ] Connect prompt copies cleanly and contains no tokenless-write, `curl`, `X-Claude-OS-Token`, raw token, or direct mutation endpoint instruction. * [ ] Starter chips dispatch `hermes-chat-prefill` with deterministic prompt text and do not require Session 07 chat to exist. ### Testing Requirements * [ ] Token hook tests cover success, malformed token response, fetch failure, demo/offline disabled states, and abort cleanup. * [ ] Prompt builder tests cover registry path insertion and forbidden instruction text. * [ ] Component tests cover token fetch, ingest POST through the hook, admin-disabled/demo/offline/token-failure states, remove, duplicate prevention, prompt copy, and starter event dispatch. * [ ] Page tests prove the new components are composed with existing read state and do not hide fallback graph content. ### Non-Functional Requirements * [ ] No token value, auth header, command output, or private runtime path is rendered or copied. * [ ] Mutating controls are disabled while pending and recover gracefully after errors. * [ ] Long paths, GitHub URLs, graph names, and prompt text do not overflow their containers on mobile or desktop. * [ ] No new client dependency is introduced. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] `bun run test -- src/hooks/__tests__/use-knowledge-graph-token.test.tsx src/lib/__tests__/knowledge-graph-connect-prompt.test.ts src/components/knowledge-graph/__tests__/knowledge-graph-ingest-card.test.tsx src/components/knowledge-graph/__tests__/knowledge-graph-connect-prompt.test.tsx src/components/knowledge-graph/__tests__/knowledge-graph-starter-chips.test.tsx src/components/knowledge-graph/__tests__/knowledge-graph-page.test.tsx` passes. * [ ] Relevant broader checks are ready for the validate workflow step. *** ## 8. Implementation Notes ### Key Considerations * Keep bridge mutation fetches inside `useKnowledgeGraphAdmin`; components should call `ingest.run` and `remove.run`. * Token fetch logic should be small and reusable. Do not widen it into a general admin client. * Do not copy the upstream prompt verbatim. Replace the script-write instruction with AI OS UI-mediated ingest guidance. * The starter chip event is a compatibility bridge for Session 07. Use `new CustomEvent("hermes-chat-prefill", { detail: text })` and avoid importing chat components in this session. * Graphify missing is a normal optional-dependency state, not a fatal page failure. ### Potential Challenges * Token fetch race with admin status: Treat token and admin status independently, then derive `canUseAdmin` from both views. * Duplicate write clicks: Preserve the hook's in-flight guard and disable form buttons while pending. * Active project removal: On success, clear local remove confirmation state and let graph-list invalidation plus the read hook reconcile selection. * Prompt safety: Tests should assert forbidden phrases, not just happy-path copy. * Mobile layout: Keep card widths constrained inside the existing horizontal gallery and avoid text-driven layout shifts. ### Relevant Considerations * \[P04] **Hermes bridge guardrails must stay intact**: UI writes must keep loopback, token, admin, non-demo, and hook-mediated boundaries. * \[P24] **Fail-closed bridges need boundary validation**: Admin-disabled, invalid token, and bridge errors stay explicit UI states. * \[P25] **Writes stay on the shared admin contract**: No route-specific or component-owned mutation fetches. * \[P25] **Preview-to-commit avoids unsafe agent writes**: The connect prompt must route new graph registration through reviewed UI/admin paths, not tokenless agent writes. * \[P23] **Thin route mount + dedicated page adapter**: Keep `/knowledge-graph` route unchanged and put behavior into modular page components. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * A write-capable UI could bypass the shared admin hook or leak token instructions into copied prompt text. * Ingest/remove controls can be double-clicked, reopened, or retried after errors while async work is still in flight. * Demo/admin-disabled/offline/graphify-missing states can silently look interactive if disabled states are not explicit. * Long local paths, GitHub URLs, prompt text, and graph names can overflow compact dashboard controls. *** ## 9. Testing Strategy ### Unit Tests * Test the token hook with mocked `/__token` success, malformed body, rejected fetch, offline browser, demo mode, and cleanup on unmount. * Test the prompt builder for active registry paths, graph names, starter questions, and absence of forbidden direct-write text. ### Integration Tests * Render `KnowledgeGraphIngestCard` with mocked token/admin/read views and assert local path ingest, GitHub URL ingest, remove, pending disablement, duplicate prevention, and all gating states. * Render `KnowledgeGraphConnectPrompt` with mocked clipboard success and failure paths, then assert user-facing copy state stays redacted. * Render `KnowledgeGraphStarterChips` and assert `hermes-chat-prefill` event details. * Extend `KnowledgeGraphPage` tests to verify new components compose with existing fallback and loaded states. ### Manual Testing * Run the dev app, open `/knowledge-graph`, and confirm the card is disabled when `HERMES_DASHBOARD_ADMIN` is not set. * Restart with `HERMES_DASHBOARD_ADMIN=1`, confirm the card requests `/__token`, then exercise a missing-graphify ingest path and visible error. * Copy the connect prompt and inspect it for safe AI OS UI-mediated instructions. * Click starter chips and confirm the event fires without breaking page state. ### Edge Cases * `/__token` returns non-JSON, missing token, empty token, or 403. * Admin status is loading while token fetch succeeds. * `graphify` is missing but admin gate is enabled. * User submits whitespace, a very long path, a GitHub shorthand URL, or a duplicate request. * User removes the active project while the graph list refreshes. * Clipboard API is unavailable or rejects. * Starter chips are clicked repeatedly before Session 07 chat exists. *** ## 10. Dependencies ### External Libraries * `@tanstack/react-query`: existing query/mutation state layer. * `lucide-react`: existing icon library for card actions. * No new external dependency is planned. ### Other Sessions * **Depends on**: Session 03 and Session 05. * **Depended by**: Session 07 (grounded Hermes chat consumes starter chips and connect affordances), Session 08 (homepage/shared-brain scripts reference the ingest behavior), Session 09 (validation and release). *** ## Next Steps Run the implement workflow step to begin AI-led 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/phase26-session06-ingest-ui-connect-prompt-starter-chips/spec.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.