> 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-session08-homepage-surface-shared-brain-scripts-oauth/spec.md). # Session Specification **Session ID**: `phase26-session08-homepage-surface-shared-brain-scripts-oauth` **Phase**: 26 - Knowledge Graph Shared Brain Port **Status**: Not Started **Created**: 2026-06-09 *** ## 1. Session Overview This session completes the remaining feature work for the Phase 26 Knowledge Graph and Shared Brain port before documentation and release closeout. Sessions 01-07 already delivered typed graph contracts, seed fixtures, read and admin bridges, ingest and removal flows, the reusable 3D renderer, the `/knowledge-graph` route, starter chips, and grounded Hermes chat. Session 08 carries that work back to the AI OS home surface and gives local agents repeatable scripts for using the dashboard as the shared graph registry. The session has three implementation lanes that all support one objective: make the Shared Brain usable from the home cockpit, command line, and Hermes setup status without false setup blockers. The home section should expose a lazy Knowledge Graph preview with seed or live stats; the scripts should install and register graphify, keep the dashboard registry as the shared source of truth, and post agent-created graph requests into the existing admin-gated ingest endpoint; the Hermes readiness fix should keep OAuth-backed providers from being marked unconfigured only because no provider API key exists in `~/.hermes/.env`. The security boundary remains the AI OS local-dev model. Graph ingest still requires the existing loopback dashboard, per-run token, admin-gated endpoint, path validation, and argv-only graphify execution from earlier sessions. The new shell scripts must not print tokens or credential values, and the OAuth fix must report provider presence/status without exposing token store contents. *** ## 2. Objectives 1. Add an AI OS home Knowledge Graph section that lazy-loads the 3D renderer, summarizes seed/live graph stats, and links operators into `/knowledge-graph`. 2. Add an idempotent `scripts/setup-graphify-brain.sh` that installs/resolves graphify, registers Hermes and Claude Code graphify skills, prepends an AI OS shared-brain note, backfills absolute registry graph paths, and restarts Hermes when available. 3. Add `scripts/graph-to-dashboard.sh` so agents can send a local path or repository URL into the dashboard `/__graphify_ingest` endpoint with token-gated authorization and bounded failure reporting. 4. Fix Hermes OAuth-provider readiness in the dev bridge and scanner parity so `openai-codex`, `nous`, `copilot`, `github-copilot`, and `anthropic-oauth` are not marked setup-needed solely because provider API keys are absent from `~/.hermes/.env`. *** ## 3. Prerequisites ### Required Sessions * [x] `phase26-session02-graph-read-bridge-registry-endpoints` - Provides loopback-only graph registry and graph read endpoints. * [x] `phase26-session03-graph-ingest-removal-admin-bridge` - Provides admin-gated `/__graphify_ingest` and registry writes. * [x] `phase26-session04-reusable-3d-code-graph-renderer` - Provides the reusable lazy 3D Knowledge Graph renderer. * [x] `phase26-session05-read-hook-route-shell-project-gallery` - Provides `/knowledge-graph`, `useKnowledgeGraph`, project gallery, and route composition. * [x] `phase26-session06-ingest-ui-connect-prompt-starter-chips` - Provides connect prompt and graph ingest UI behavior. * [x] `phase26-session07-hermes-chat-grounding-graph-toolset` - Provides grounded Hermes chat and graphify toolset forwarding. ### Required Tools/Knowledge * Bun 1.3.14, React 19, TypeScript, TanStack Query, Tailwind CSS 4, Vitest, and Testing Library. * Bash shell scripting with `set -euo pipefail`, quoted paths, structured JSON parsing, and safe curl usage. * Existing Knowledge Graph hooks, components, and parser contracts under `src/hooks/`, `src/components/knowledge-graph/`, and `src/lib/knowledge-graph-*`. * Existing Hermes readiness endpoints and aggregate scanner code in `scripts/lib/hermes-dev-bridge.ts` and `scripts/lib/hermes-scanner.ts`. * Upstream behavior references in `/home/aiwithapex/projects/claudeos/claude-os-v2.4/` for behavior mapping only. ### Environment Requirements * Local Vite dev server can expose `/__token` and `/__graphify_ingest`. * `graphify`, `uv`, `pipx`, `python3`, `curl`, and `hermes` may or may not be installed; scripts must degrade with explicit messages. * Generated graph artifacts remain local and ignored. * Live graphify execution remains optional for tests; smoke coverage should not require live credentials or network access. *** ## 4. Scope ### In Scope (MVP) * Operator can see Knowledge Graph status on the home cockpit - implemented as a dedicated `src/components/home/` section with lazy 3D preview, seed/live stats, provenance, loading, empty, error, and offline states. * Operator can navigate from home to the full `/knowledge-graph` surface - implemented with a visible route link and bounded project labels. * Operator can run Shared Brain setup repeatedly - implemented with install/resolve/symlink steps, skill registration, idempotent note prepending, structured registry backfill, and bounded restart behavior. * Agent or operator can post a graph target into the dashboard - implemented with reachability check, token read, JSON-encoded payload, token header, curl timeout, and safe success/error reporting. * Hermes OAuth-backed providers do not show false setup blockers - implemented by classifying OAuth providers separately from API-key providers in both dev bridge and scanner projections. * Generated `graphify-out/` output stays out of git - implemented by adding the `.gitignore` entry. * Focused smoke/unit coverage proves UI states, script behavior, OAuth readiness, and ignore hygiene. ### Out of Scope (Deferred) * Final docs, changelog, parity sign-off, release bump, full validation, accessibility review, and security review - *Reason: Session 09 owns closeout.* * New Knowledge Graph endpoint behavior or bridge write capability - *Reason: Sessions 02-07 already own graph bridges and chat grounding.* * Live graphify installation in tests - *Reason: smoke coverage should validate script safety without depending on external package managers or network.* * New public collection sources or Trend Finder graph integration - *Reason: Phase 26 scope is local code graph Shared Brain behavior.* *** ## 5. Technical Approach ### Architecture Keep the home route thin by extracting Knowledge Graph presentation into `src/components/home/knowledge-graph-section.tsx` and pure summary derivation into `src/lib/knowledge-graph-home-summary.ts`. The section should consume `useKnowledgeGraph({ enabled: true })`, lazy-load `KnowledgeGraph3D`, and render the existing seeded fallback when live bridge reads are unavailable. It should preserve the dense AI OS home layout and avoid creating a second route-specific graph contract. Add two Bash scripts under `scripts/`. `setup-graphify-brain.sh` should use the repo root as the dashboard root, prefer existing graphify binaries, install through `uv`, `pipx`, or a local venv only when absent, symlink to `~/.local/bin/graphify`, run platform skill installs when the binary is available, prepend an AI OS shared-brain note to Hermes and Claude Code graphify skills only when missing, backfill registry `graphPath` values with a structured JSON parser, and restart Hermes if `hermes gateway restart` is available. `graph-to-dashboard.sh` should take one target argument, use `AI_OS_URL` as the primary dashboard base URL with optional compatibility fallback, read `/__token`, and POST into `/__graphify_ingest` with the existing token header and bounded curl timeouts. Extract provider readiness semantics in the Hermes bridge so API-key providers and OAuth providers are not conflated. API-key providers still check the declared environment key when a known key map exists. OAuth providers are considered provider-auth capable when the provider is set in `config.yaml`; the actual token store is not read or exposed by this session. Mirror the same classification in the scanner path so aggregate/home/settings status does not drift from bridge status. ### Design Patterns * Thin route plus component extraction: home route imports and renders a dedicated section rather than embedding complex Knowledge Graph UI inline. * Pure projection before rendering: graph summary, top files, savings, and provenance labels are derived in a testable helper. * Lazy vendor loading: the 3D renderer remains lazy and provides explicit loading, error, and offline fallback states. * Idempotent local scripts: setup and note-prepend work should be safe to rerun and should not duplicate note blocks or mutate unrelated files. * Boundary validation: dashboard ingest remains token-gated at the existing endpoint, and shell scripts quote paths and encode JSON instead of building ad hoc payload strings. * Provider classification helper: OAuth provider detection is centralized so status and connection parity stay aligned. ### Technology Stack * React 19, TypeScript, TanStack Query, Tailwind CSS 4, and lucide-react. * Existing `useKnowledgeGraph`, `KnowledgeGraph3D`, graph parsers, and seed data. * Bash with `curl`, `python3` or `bun`/Node JSON parsing, and POSIX-safe quoting. * Vitest and Testing Library for unit, component, bridge, scanner, and script smoke coverage. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ---------- | | `src/lib/knowledge-graph-home-summary.ts` | Pure home summary projection for registry, active graph, provenance, stats, and savings | \~140 | | `src/lib/__tests__/knowledge-graph-home-summary.test.ts` | Unit tests for summary derivation, fallback labels, bounded paths, and deterministic ordering | \~150 | | `src/components/home/knowledge-graph-section.tsx` | Home Knowledge Graph section with lazy preview, stats, state handling, and CTA | \~240 | | `src/components/home/__tests__/knowledge-graph-section.test.tsx` | Component tests for loading, empty, error, offline, demo, live, and CTA states | \~220 | | `scripts/setup-graphify-brain.sh` | AI OS shared-brain setup script for graphify install, skill registration, registry note, path backfill, and restart | \~140 | | `scripts/graph-to-dashboard.sh` | Agent-to-dashboard ingest helper with reachability, token read, POST, timeout, and safe report | \~100 | | `scripts/lib/__tests__/graphify-shared-brain-scripts.test.ts` | Smoke tests for script syntax, AI OS naming, safe token handling, JSON encoding, and idempotency markers | \~140 | ### Files to Modify | File | Changes | Est. Lines | | ------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ---------- | | `src/routes/index.tsx` | Import and mount the home Knowledge Graph section without expanding route-local logic | \~30 | | `scripts/lib/hermes-dev-bridge.ts` | Add OAuth provider readiness classification and avoid false setup-needed state for OAuth providers | \~120 | | `scripts/lib/hermes-scanner.ts` | Mirror provider readiness classification for aggregate parity | \~80 | | `scripts/lib/__tests__/hermes-dev-bridge.test.ts` | Add bridge regression coverage for API-key and OAuth providers | \~160 | | `scripts/lib/__tests__/hermes-scanner.test.ts` | Add scanner regression coverage for OAuth provider parity | \~100 | | `.gitignore` | Add `graphify-out/` generated output ignore entry | \~3 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Home renders a Knowledge Graph section that lazy-loads the 3D preview and displays seed or live graph stats with explicit loading, empty, error, and offline states. * [ ] Home section links to `/knowledge-graph` and keeps long project names, paths, and stats bounded on mobile and desktop. * [ ] `scripts/setup-graphify-brain.sh` is idempotent, uses AI OS wording, resolves or installs graphify, symlinks it, registers Hermes and Claude Code skills, prepends one shared-brain note, backfills absolute registry paths, and restarts Hermes when available. * [ ] `scripts/graph-to-dashboard.sh` reads the local token, posts to `/__graphify_ingest`, handles timeout/error/non-JSON responses, and never prints the token. * [ ] `openai-codex`, `nous`, `copilot`, `github-copilot`, and `anthropic-oauth` are not marked setup-needed solely because an API key is missing from `~/.hermes/.env`. * [ ] Known API-key providers still surface setup-needed or unconfigured states when their required key is absent. * [ ] `graphify-out/` is ignored by git. ### Testing Requirements * [ ] Home summary helper tests cover summary stats, provenance labels, top file ordering, missing active graph fallback, and bounded display paths. * [ ] Home section tests cover live, seed fallback, demo, loading, empty, error, offline, lazy renderer fallback, and accessible navigation states. * [ ] Script smoke tests cover `bash -n`, idempotency markers, AI OS wording, URL/env fallback, token redaction, JSON payload encoding, curl timeout, and no Unicode output. * [ ] Hermes bridge and scanner tests cover OAuth provider readiness, API-key provider missing-key behavior, unknown provider fallback, and sanitized output. * [ ] Focused tests and script syntax checks pass. ### Non-Functional Requirements * [ ] No token values, auth headers, credential-shaped strings, raw command output, or private local paths are rendered, copied, or logged. * [ ] The 3D home preview does not expand bundle cost eagerly and uses lazy import fallback states. * [ ] Shell scripts use quoted paths, structured JSON parsing, bounded curl timeouts, and explicit failure messages. * [ ] No new client dependency is introduced. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] `bash -n scripts/setup-graphify-brain.sh scripts/graph-to-dashboard.sh` passes. * [ ] `bun run test -- src/lib/__tests__/knowledge-graph-home-summary.test.ts src/components/home/__tests__/knowledge-graph-section.test.tsx scripts/lib/__tests__/graphify-shared-brain-scripts.test.ts scripts/lib/__tests__/hermes-dev-bridge.test.ts scripts/lib/__tests__/hermes-scanner.test.ts` passes. * [ ] Relevant broader checks are ready for the validate workflow step. *** ## 8. Implementation Notes ### Key Considerations * Keep the home section compact. It should advertise the Shared Brain and provide a preview, not duplicate the full `/knowledge-graph` route. * Use `AI_OS_URL` as the primary script environment variable. Preserve compatibility only where it avoids breaking existing local habits, and keep visible wording AI OS-native. * The existing dashboard token header may retain its compatibility name if the bridge contract already uses it; do not rename token headers without a dedicated migration. * Registry path backfill should use a structured JSON parser and write only the graph registry file. * Tests should not run live graphify installs or real dashboard ingests. ### Potential Challenges * Home route size: Mitigate by placing derivation and presentation in separate files and only mounting the section in `index.tsx`. * 3D vendor budget: Keep `KnowledgeGraph3D` lazy-loaded and do not add new graph visualization dependencies. * Shell portability: Keep scripts Bash-specific with `#!/usr/bin/env bash`, quote variables, and avoid Unicode status glyphs. * OAuth readiness ambiguity: Mark OAuth providers as not missing API-key setup when configured, but do not claim the OAuth token is valid unless an existing Hermes status check proves it. * Token safety: Parse and pass token values without echoing them in success, error, or debug output. ### Relevant Considerations * \[P01] **3D vendor chunk budget**: Keep Knowledge Graph home preview lazy and avoid eager `react-force-graph-3d` imports. * \[P04] **Hermes bridge guardrails must stay intact**: Do not add new unauthenticated bridge behavior while fixing setup status. * \[P21] **OAuth material stays script-only**: Do not expose OAuth token store contents, bearer headers, or token-shaped strings. * \[P24] **Fail-closed bridges need boundary validation**: Preserve loopback, token, body-size, and schema checks at `/__graphify_ingest`. * \[P18] **Lazy imports plus cleanup-first effects make 3D UI safe**: Apply the existing lazy/fallback pattern to the home preview. * \[P23] **Thin route mount + dedicated page adapter**: Keep route changes small and component-driven. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Home preview could eagerly load the heavy 3D graph stack or fail without explicit loading/offline/error states. * Shared-brain scripts could leak local tokens, duplicate skill notes, or mutate registry paths with string manipulation. * OAuth-backed Hermes providers could still be blocked by API-key assumptions or be overreported as fully authenticated. * Agent-to-dashboard ingest could bypass existing admin boundaries if token handling or endpoint selection is changed. *** ## 9. Testing Strategy ### Unit Tests * Test `knowledge-graph-home-summary` for stats, provenance, savings, top files, missing graph fallback, and deterministic ordering. * Test Hermes provider readiness helpers through bridge and scanner fixtures for OAuth and API-key provider cases. * Test script files by reading their contents for AI OS wording, idempotency markers, token redaction, URL fallback, and JSON payload encoding. ### Integration Tests * Render `KnowledgeGraphSection` with mocked `useKnowledgeGraph` states for loading, live success, seeded fallback, demo, empty, error, and offline views. * Extend Hermes dev bridge route tests to verify `/__hermes_status` and `/__hermes_connections` remain token-free and report OAuth/API-key provider readiness correctly. * Extend scanner tests to prove aggregate parity with bridge setup detection for OAuth providers. ### Manual Testing * Open the home route with the dev server running and confirm the Knowledge Graph section appears without layout overlap. * Run `bash -n scripts/setup-graphify-brain.sh scripts/graph-to-dashboard.sh`. * With a local dashboard running, run `scripts/graph-to-dashboard.sh ` against a throwaway fixture only if manual live ingest is desired. * Configure a Hermes `config.yaml` with an OAuth-backed provider and no matching `.env` API key, then confirm setup is not falsely blocked. ### Edge Cases * Missing graph registry should show seed fallback or explicit empty state without crashing. * Offline browser state should not attempt repeated live fetches without a clear status. * Existing graphify skill note should not be duplicated on rerun. * Dashboard token endpoint returning malformed JSON should produce a bounded error without printing token-like text. * Unknown Hermes provider should not be treated as an API-key failure unless an explicit provider key mapping exists. *** ## 10. Dependencies ### External Libraries * No new external libraries. ### Other Sessions * **Depends on**: `phase26-session02-graph-read-bridge-registry-endpoints`, `phase26-session03-graph-ingest-removal-admin-bridge`, `phase26-session04-reusable-3d-code-graph-renderer`, `phase26-session05-read-hook-route-shell-project-gallery`, `phase26-session06-ingest-ui-connect-prompt-starter-chips`, and `phase26-session07-hermes-chat-grounding-graph-toolset`. * **Depended by**: `phase26-session09-documentation-validation-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-session08-homepage-surface-shared-brain-scripts-oauth/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.