> 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_26/prd_phase_26.md).

# PRD Phase 26: Knowledge Graph Shared Brain Port

**Status**: Complete **Sessions**: 9 (initial estimate) **Estimated Duration**: 9-12 days

**Progress**: 9/9 sessions (100%)

***

## Overview

Phase 26 ports the Claude OS `v2.4` Knowledge Graph line of work into AI OS using the AI OS architecture. The original codebase shipped a new release (`v2.4`, whose changelog also contains the later `V2.5` "Shared Brain" work). AI OS currently reflects the `v2.3` baseline. The complete change set being ported is captured in the audited diff at `/home/aiwithapex/projects/claudeos/DIFF_V2.3_V2.4.md` and the full new tree lives at `/home/aiwithapex/projects/claudeos/claude-os-v2.4/`.

The upstream feature wires the external `graphify` tool into the dashboard as a per-project code graph: a Knowledge Graph route, a reusable 3D graph renderer, dashboard-driven ingest/list/stream/remove endpoints, a graph registry, a seed graph for the app's own repo, and Hermes chat grounding against the active project's graph. Upstream concentrates this in three large files (`vite.config.ts`, `src/routes/codegraph.tsx`, `src/components/graphify-graph-3d.tsx`).

AI OS does **not** copy those files. AI OS keeps its typed, modular, admin-gated architecture: thin TanStack route, dedicated page adapter, modular feature components, typed read/admin contracts, registered dev/admin bridge modules under `scripts/lib/`, demo fixtures, and broad Vitest/Testing Library/Playwright coverage. The product behavior reaches parity with `v2.4`/`V2.5`; the file shape stays AI OS-native.

Confirmed scope decisions for this phase:

* **Comprehensive (V2.4 + V2.5)**: full live ingest behind the AI OS admin gate (loopback + per-run token + `HERMES_DASHBOARD_ADMIN=1` + non-demo + hook-mediated browser path), plus Shared Brain setup scripts, GitHub URL ingest, auto-prune, removal endpoint, and Hermes graph grounding. The external `graphify` binary is an optional runtime dependency; demo/seed fallback renders when it is absent.
* **AI OS-native naming**: route `/knowledge-graph`, files under `src/components/knowledge-graph/`, hook `src/hooks/use-knowledge-graph.ts`, contracts `src/lib/knowledge-graph-types.ts`, bridges `scripts/lib/knowledge-graph-dev-bridge.ts` and `scripts/lib/knowledge-graph-admin-bridge.ts`. Endpoint wire paths keep the upstream `/__graphify_*` names for prompt/script compatibility.
* **Wire the hero for real**: the dormant upstream KG visual work (aurora / statue / constellation CSS plus `thinker.webp`) is built into a real, functional Knowledge Graph header rather than copied as dead code.

***

## Progress Tracker

| Session | Name                                        | Status   | Est. Tasks | Validated  |
| ------- | ------------------------------------------- | -------- | ---------- | ---------- |
| 01      | Graph Data Contracts And Seed Fixtures      | Complete | \~12-25    | 2026-06-09 |
| 02      | Graph Read Bridge And Registry Endpoints    | Complete | \~12-25    | 2026-06-09 |
| 03      | Graph Ingest And Removal Admin Bridge       | Complete | \~12-25    | 2026-06-09 |
| 04      | Reusable 3D Code Graph Renderer             | Complete | \~12-25    | 2026-06-09 |
| 05      | Read Hook Route Shell And Project Gallery   | Complete | \~12-25    | 2026-06-09 |
| 06      | Ingest UI Connect Prompt And Starter Chips  | Complete | \~12-25    | 2026-06-09 |
| 07      | Hermes Chat Grounding And Graph Toolset     | Complete | \~12-25    | 2026-06-09 |
| 08      | Homepage Surface Shared Brain Scripts OAuth | Complete | \~12-25    | 2026-06-09 |
| 09      | Documentation Validation And Release        | Complete | \~12-25    | 2026-06-09 |

***

## Completed Sessions

* `phase26-session01-graph-data-contracts-seed-fixtures`
* `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`
* `phase26-session07-hermes-chat-grounding-graph-toolset`
* `phase26-session08-homepage-surface-shared-brain-scripts-oauth`
* `phase26-session09-documentation-validation-release`

***

## Upcoming Sessions

* None. Phase 26 is complete.

Session 01 validation passed on 2026-06-09. Session 02 validation passed on 2026-06-09. Session 03 validation passed on 2026-06-09. Session 04 validation passed on 2026-06-09. Session 05 validation passed on 2026-06-09. Session 06 validation passed on 2026-06-09. Session 07 validation passed on 2026-06-09. Session 08 validation passed on 2026-06-09. Session 09 validation passed on 2026-06-09. The phase is complete, and the next workflow step is `audit`.

***

## Objectives

1. Land typed Knowledge Graph contracts and seed fixtures so a graphify NetworkX node-link graph, registry entry, god nodes, metadata, and savings estimate parse safely and reject malformed payloads.
2. Add a loopback-only graph read bridge exposing registry list (with auto-prune) and streamed graph reads with path confinement and a bundled seed fallback.
3. Add an admin-gated ingest/removal bridge that shells `graphify` and `git` through argv arrays only, guards vendored deps and oversized graphs, computes metadata, and writes path-confined graphs plus absolute-path registry entries.
4. Build a reusable 3D code graph renderer (god nodes, community clusters, density toggle, bloom, fly-to, legend, capping) reusing the existing AI OS force-graph type and lifecycle patterns.
5. Add a read hook, thin route, dedicated page adapter, scrollable project gallery, side rail stats, and a real wired Knowledge Graph hero header, plus the sidebar nav entry.
6. Add the admin-gated ingest UI, the copyable connect-with-Hermes prompt, and starter-question chips that prefill the grounded Hermes chat.
7. Ground Hermes chat against the active graph (seed context, grounding chip, `toolsets`/`yolo` forwarding, graphify skill) without weakening the admin gate.
8. Port the homepage Knowledge Graph section, the Shared Brain setup and dashboard ingest scripts, and the upstream Hermes OAuth-provider setup false-positive fix.
9. Document, validate, security-review, and release the activated Knowledge Graph surface with parity sign-off against `v2.4`/`V2.5`.

***

## Prerequisites

* Phase 25 completed (Hermes Mission Control Activation).
* Phase 18 3D Mnemosyne constellation completed (reusable force-graph patterns: `src/components/memory-graph-3d.tsx`, `src/lib/graph-types.ts`, `src/components/memory-graph-loader.tsx`).
* Phase 16-17 Hermes bridge, admin gate, token, and chat foundation completed (`scripts/lib/hermes-dev-bridge.ts`, `scripts/lib/hermes-admin-bridge.ts`, `src/hooks/use-hermes.ts`, `src/hooks/use-hermes-admin.ts`, `src/components/hermes/chat/`).
* Audited source diff available at `/home/aiwithapex/projects/claudeos/DIFF_V2.3_V2.4.md`.
* Full new reference tree available at `/home/aiwithapex/projects/claudeos/claude-os-v2.4/`.

***

## Technical Considerations

### Architecture

Keep the AI OS architecture authoritative. The upstream concentration of logic in `vite.config.ts`, `src/routes/codegraph.tsx`, and `src/components/graphify-graph-3d.tsx` is a reference for behavior, not a copy target. Map upstream into AI OS layers:

* Upstream `vite.config.ts` graph middleware -> two registered bridge modules: `scripts/lib/knowledge-graph-dev-bridge.ts` (loopback-only reads) and `scripts/lib/knowledge-graph-admin-bridge.ts` (token + admin writes), wired in `vite.config.ts` via `configureServer`, mirroring how `registerHermesDevBridge` and `registerHermesAdminBridge` are registered.
* Upstream `src/routes/codegraph.tsx` (765 lines) -> thin route `src/routes/knowledge-graph.tsx` plus a dedicated page adapter and modular components under `src/components/knowledge-graph/` (P23 thin-route lesson).
* Upstream `src/components/graphify-graph-3d.tsx` (625 lines) -> `src/components/knowledge-graph/knowledge-graph-3d.tsx` reusing `src/lib/graph-types.ts` and the lazy-import/cleanup-first effect pattern from the existing Mnemosyne renderer (P18 lesson).
* Local `interface` blocks and ad hoc JSON -> typed contracts in `src/lib/knowledge-graph-types.ts` with parsers that reject malformed payloads.
* No fixtures upstream -> demo fixtures in `src/lib/knowledge-graph-demo-data.ts` plus a checked-in seed graph and registry under `src/data/graphs/`.

Endpoint wire paths stay `/__graphify_list`, `/__graphify_graph`, `/__graphify_ingest`, and `/__graphify_remove` so the copied connect prompt and the `graph-to-dashboard` helper remain compatible.

### Security And Safety Model

The upstream ingest endpoints are loopback-gated, and mutating endpoints are token-gated. AI OS tightens this further. Every mutating Knowledge Graph endpoint must keep the full AI OS admin preflight. The server enforces the first three checks, and the browser/admin hook enforces the non-demo, hook-mediated path:

* Loopback request.
* Valid per-run `X-Claude-OS-Token`.
* `HERMES_DASHBOARD_ADMIN=1`.
* Non-demo UI mode.
* Hook-mediated browser path.

Process-spawn safety (the highest-risk surface in this phase):

* `graphify` and `git` are invoked through `execFileSync` with argv arrays only, never shell strings (mirrors upstream `/home/aiwithapex/projects/claudeos/claude-os-v2.4/vite.config.ts:549-563`).
* Graph ids are sanitized and path-confined to the shared graph directory.
* GitHub/git URLs are validated before a shallow clone into a temp dir that is always cleaned up.
* Ingest refuses graphs over 12,000 nodes and guards against vendored-dependency blowups (upstream `vite.config.ts:579-599`).
* `graphify` stays an optional dependency: when the binary is absent, reads serve the seed/bundled graph and the ingest UI degrades to an explicit disabled state. Live ingest never becomes a hard dependency.

### Technologies

* React 19 and TypeScript, TanStack Router/Query, existing AI OS query keys.
* `react-force-graph-3d` (`^1.29.1`) and `three` (`^0.184.0`) -- already AI OS dependencies; no new client graph dependency is introduced.
* Vite local dev bridge modules under `scripts/lib/` with `execFileSync` argv process spawning and `fs`/`os` temp handling.
* Vitest, Testing Library, and Playwright for contract, bridge, component, hook, route, responsive, and e2e coverage.

### Risks

* Process-spawn surface: the ingest bridge runs external binaries. Keep argv arrays, the admin preflight, path confinement, node cap, and temp cleanup; add rejection-path tests for unauthorized, non-loopback, oversized, and malformed ingests.
* 3D vendor chunk budget (P01): the renderer must stay lazy-loaded and share the existing force-graph chunk; do not regress gzip budgets.
* External tool optionality: graphify may be uninstalled. Demo/seed fallback and a disabled ingest state must keep the route useful without it.
* Hermes chat grounding must not weaken the admin gate: seed context, toolsets, and yolo are presentation/argv additions on the already-authorized chat path, not a new unauthenticated write surface.
* Seed graph staleness: the checked-in AI OS self-graph is a snapshot; document it as a seed and let live ingest supersede it.
* Naming drift: AI OS uses `/knowledge-graph` while wire paths keep `/__graphify_*`; document both so future `v2.x` diffs map cleanly.

### Relevant Considerations

* \[P01] **3D vendor chunk budget**: `react-force-graph-3d` and `three` dominate client JS; the new renderer must stay lazy and share the existing chunk.
* \[P04] **Hermes bridge guardrails must stay intact**: the new read bridge stays loopback-only; the new ingest/remove bridge keeps loopback + token + admin + no-clobber path safety.
* \[P18] **Lazy imports plus cleanup-first effects make 3D UI safe**: reuse the Mnemosyne approach so the renderer stays SSR-friendly and testable.
* \[P24] **Fail-closed bridges need boundary validation**: the ingest/remove bridge keeps loopback, token, body-size, and schema checks at the boundary.
* \[P25] **Writes stay on the shared admin contract**: graph ingest/remove flow through a dedicated admin hook/bridge; do not add ad hoc component fetches or unguarded shell/git/workspace paths without a separate threat model.

***

## Success Criteria

Phase complete when:

* [x] All 9 sessions completed and validated.
* [x] Typed Knowledge Graph contracts parse seed/live graphs and reject malformed payloads; demo fixtures and a checked-in seed graph + registry exist.
* [x] `/__graphify_list` (with auto-prune) and `/__graphify_graph` serve through a loopback-only read bridge with path confinement and bundled fallback.
* [x] `/__graphify_ingest` and `/__graphify_remove` run only behind the full AI OS admin gate, spawn graphify/git via argv arrays, enforce the node cap and vendored-deps guard, and write absolute-path registry entries.
* [x] The reusable 3D renderer shows god nodes, community clusters, density toggle, capping notice, and legend, lazy-loaded with clean teardown.
* [x] `/knowledge-graph` renders header (real wired hero), project gallery, 3D panel, side rail stats, ingest card, and connect prompt, with the sidebar nav entry present.
* [x] Hermes chat can be grounded against the active graph (seed context, grounding chip, toolsets/yolo, graphify skill) without weakening the gate.
* [x] The homepage Knowledge Graph section, Shared Brain setup/ingest scripts, and the Hermes OAuth-provider setup false-positive fix are ported.
* [x] Docs, full test suite, accessibility review, security review, admin-gate verification, responsive/e2e, and parity sign-off against `v2.4`/`V2.5` pass; release version bumped.

***

## Dependencies

### Depends On

* Phase 25: Hermes Mission Control Activation (chat, admin bridge, token).
* Phase 18: Hermes Memory And Visualization (3D force-graph patterns).
* Phase 16-17: Hermes bridge, admin gate, and chat foundation.
* Audited diff `/home/aiwithapex/projects/claudeos/DIFF_V2.3_V2.4.md` and reference tree `/home/aiwithapex/projects/claudeos/claude-os-v2.4/`.

### Enables

* A per-project Knowledge Graph surface and grounded Hermes chat in AI OS.
* The five-tier Knowledge Graph "unlocks" roadmap (`/home/aiwithapex/projects/claudeos/claude-os-v2.4/docs/knowledge-graph-unlocks.md`).
* Future multi-project Shared Brain expansion and graph-backed agent tooling.

***

## Source Project Reference Links

### AI OS Targets (where ported behavior will live)

* [Knowledge Graph route (new)](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/src/routes/knowledge-graph.tsx)
* [Knowledge Graph components (new)](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/src/components/knowledge-graph/README.md)
* [Knowledge Graph read hook (new)](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/src/hooks/use-knowledge-graph.ts)
* [Knowledge Graph contracts (new)](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/src/lib/knowledge-graph-types.ts)
* [Knowledge Graph demo fixtures (new)](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/src/lib/knowledge-graph-demo-data.ts)
* [Knowledge Graph read bridge (new)](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/scripts/lib/knowledge-graph-dev-bridge.ts)
* [Knowledge Graph admin bridge (new)](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/scripts/lib/knowledge-graph-admin-bridge.ts)
* [Seed graph + registry (new)](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/src/data/graphs/README.md)
* [Existing 3D renderer to reuse](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/src/components/memory-graph-3d.tsx)
* [Existing force-graph types to reuse](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/src/lib/graph-types.ts)
* [Existing 3D loader to reuse](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/src/components/memory-graph-loader.tsx)
* [Vite dev-bridge registration site](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/vite.config.ts)
* [Hermes read bridge pattern](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/scripts/lib/hermes-dev-bridge.ts)
* [Hermes admin bridge pattern](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/scripts/lib/hermes-admin-bridge.ts)
* [Hermes chat components](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/src/components/hermes/chat/README.md)
* [Hermes admin hook (chat stream)](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/src/hooks/use-hermes-admin.ts)
* [Sidebar nav](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/src/components/app-sidebar.tsx)
* [Homepage route](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/src/routes/index.tsx)
* [Hermes status bridge (OAuth fix target)](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/scripts/lib/hermes-dev-bridge.ts)
* [Hermes scanner (aggregate parity check)](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/scripts/lib/hermes-scanner.ts)
* [AI OS changelog](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/aios/docs/CHANGELOG.md)

### Claude OS v2.4 Reference (source of the port)

* [Audited diff](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/DIFF_V2.3_V2.4.md)
* [Reference tree root](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.4)
* [Reference codegraph route](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.4/src/routes/codegraph.tsx)
* [Reference 3D renderer](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.4/src/components/graphify-graph-3d.tsx)
* [Reference Vite middleware/endpoints](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.4/vite.config.ts)
* [Reference Hermes route changes](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.4/src/routes/agents.hermes.tsx)
* [Reference homepage changes](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.4/src/routes/index.tsx)
* [Reference sidebar change](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.4/src/components/app-sidebar.tsx)
* [Reference KG CSS](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.4/src/styles.css)
* [Reference KG asset](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.4/src/assets/hermes-art/knowledge-graph/thinker.webp)
* [Reference seed registry](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.4/src/data/graphs/index.json)
* [Reference seed graph](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.4/src/data/graphs/claude-os.json)
* [Reference setup script](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.4/scripts/setup-graphify-brain.sh)
* [Reference ingest helper script](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.4/scripts/graph-to-dashboard.sh)
* [Reference GRAPHIFY.md](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.4/GRAPHIFY.md)
* [Reference GRAPHIFY\_HANDOVER.md](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.4/GRAPHIFY_HANDOVER.md)
* [Reference HANDOVER.md](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.4/HANDOVER.md)
* [Reference unlocks roadmap](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.4/docs/knowledge-graph-unlocks.md)
* [Reference CHANGELOG](https://github.com/moshehbenavraham/ai-os/blob/main/home/aiwithapex/projects/claudeos/claude-os-v2.4/CHANGELOG.md)

***

## Folded Source-Verified Change Inventory

This section folds the audited diff so the source document can be referenced from one place. The inventory is the porting work-list. Every entry carries the exact `v2.4` source location so developers can find the original code. Line numbers are the 2026-06-09 audit snapshot -- treat them as anchors and re-confirm before editing. Reference root `v2.4/` = `/home/aiwithapex/projects/claudeos/claude-os-v2.4/`.

Audit totals: 11 files added, 10 modified common files, 0 removed. The implementation spans both the `V2.4` (Knowledge Graph) and `V2.5` (Shared Brain) changelog entries even though the directory is named `v2.4`.

### Added Files (port targets)

| `v2.4` source                                                      | What it is                                                                                                                               | AI OS port target                                                                | Session |
| ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ------- |
| `v2.4/src/routes/codegraph.tsx` (765 lines)                        | Knowledge Graph page: connect prompt, live registry polling, graph load, god-node focus, gallery, ingest, hero, side rail, grounded chat | `src/routes/knowledge-graph.tsx` (thin) + `src/components/knowledge-graph/*`     | 05, 06  |
| `v2.4/src/components/graphify-graph-3d.tsx` (625 lines)            | Reusable 3D renderer: density/capping/god nodes, bloom/starfield/orbit, cluster force, fly-to, custom meshes, legend                     | `src/components/knowledge-graph/knowledge-graph-3d.tsx` (reuse `graph-types.ts`) | 04      |
| `v2.4/src/data/graphs/index.json` (40 lines)                       | Seed registry: project id/name/lang/color, counts, god nodes, graphPath                                                                  | `src/data/graphs/index.json` (AI OS self-graph entry)                            | 01      |
| `v2.4/src/data/graphs/claude-os.json` (158 KB, minified)           | Raw graphify NetworkX node-link graph (269 nodes, 229 links, 85 communities, 96% extracted)                                              | `src/data/graphs/<ai-os-id>.json` (generated AI OS self-graph)                   | 01      |
| `v2.4/src/assets/hermes-art/knowledge-graph/thinker.webp` (179 KB) | Hero art asset (dormant upstream)                                                                                                        | `src/assets/.../knowledge-graph/thinker.webp` (wired for real)                   | 05      |
| `v2.4/scripts/setup-graphify-brain.sh` (94 lines)                  | Install graphify, symlink binary, register skills, shared-brain note, backfill absolute graphPath, restart                               | `scripts/setup-graphify-brain.sh` (AI OS-adapted)                                | 08      |
| `v2.4/scripts/graph-to-dashboard.sh` (70 lines)                    | Dashboard reachability/token, POST to `__graphify_ingest`, report                                                                        | `scripts/graph-to-dashboard.sh` (AI OS-adapted)                                  | 08      |
| `v2.4/GRAPHIFY.md` (46 lines)                                      | Shared-brain model, one-command setup, usage, cost note                                                                                  | `docs/` Knowledge Graph guide                                                    | 09      |
| `v2.4/GRAPHIFY_HANDOVER.md` (80 lines)                             | Context, stack, decisions, data model, endpoint contract, roadmap                                                                        | folded into docs/handover                                                        | 09      |
| `v2.4/HANDOVER.md` (129 lines)                                     | TL;DR, run/env, file map, endpoints, renderer notes, gotchas, curl checks                                                                | folded into docs/handover                                                        | 09      |
| `v2.4/docs/knowledge-graph-unlocks.md` (61 lines)                  | Five-tier roadmap and recommended sequence                                                                                               | `docs/knowledge-graph-unlocks.md`                                                | 09      |

### Modified Common Files (changes to port)

| `v2.4` source                         | Diffstat   | What changed                                                                                                                                                                                                   | AI OS port target                                                                                                                | Session        |
| ------------------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -------------- |
| `v2.4/vite.config.ts`                 | +458 / -4  | Graph ingest/list/stream/remove middleware (302-719), Hermes OAuth-provider setup fix (810-857), Hermes chat toolsets/yolo (953-1100)                                                                          | read bridge (02), admin bridge (03), chat bridge args (07), Hermes status/scanner fix (08)                                       | 02, 03, 07, 08 |
| `v2.4/src/routes/agents.hermes.tsx`   | +249 / -32 | `ReactNode` import; exported `useHermesStatus`/`HermesChat` + KG props; prefill listener; first-turn seed prefix; toolsets/yolo payload; grounding chip; unique session key; assistant bubble + `ChatMarkdown` | existing `src/components/hermes/chat/*`, `src/hooks/use-hermes.ts`, `src/hooks/use-hermes-admin.ts`, `agents.hermes.tsx` adapter | 07             |
| `v2.4/src/routes/index.tsx`           | +64 / -0   | Lazy graph import + seed stats (100-106); homepage Knowledge Graph section (1495-1550)                                                                                                                         | `src/routes/index.tsx` + `src/components/home/*`                                                                                 | 08             |
| `v2.4/src/styles.css`                 | +54 / -0   | `kg-*` aurora/statue/constellation animation classes/keyframes (492-544); dormant upstream                                                                                                                     | `src/styles.css` (wired into real hero)                                                                                          | 05             |
| `v2.4/src/components/app-sidebar.tsx` | +2 / -1    | `Waypoints` import; "Knowledge Graph" nav entry (90)                                                                                                                                                           | `src/components/app-sidebar.tsx`                                                                                                 | 05             |
| `v2.4/src/routeTree.gen.ts`           | +21 / -0   | Generated route registration                                                                                                                                                                                   | regenerated by TanStack router plugin; do not hand-edit                                                                          | 05             |
| `v2.4/CHANGELOG.md`                   | +99 / -0   | `V2.5` Shared Brain entry (8-56); `V2.4` Knowledge Graph entry (58-104)                                                                                                                                        | `docs/CHANGELOG.md` (AI OS entry)                                                                                                | 09             |
| `v2.4/.gitignore`                     | +3 / -0    | Ignore block for `graphify-out/` (40-42)                                                                                                                                                                       | `.gitignore`                                                                                                                     | 08             |
| `v2.4/README.md`                      | +0 / -2    | Removed explicit `0.1.1` version line                                                                                                                                                                          | N/A (AI OS keeps its own versioning)                                                                                             | 09 (note only) |
| `v2.4/package.json`                   | +0 / -1    | Removed `"version": "0.1.1"`                                                                                                                                                                                   | N/A (AI OS keeps its own versioning)                                                                                             | 09 (note only) |

Total upstream change: 21 files changed, 2,861 insertions, 40 deletions.

### Backend Endpoint Anchors (`v2.4/vite.config.ts`)

| Feature                                                                                                                 | `v2.4/vite.config.ts` lines |
| ----------------------------------------------------------------------------------------------------------------------- | --------------------------- |
| New Node imports for process/file/temp handling                                                                         | `2`, `7`, `14`, `19`        |
| Shared graph directory constant                                                                                         | `302-308`                   |
| `GET /__graphify_list` registry read + auto-prune                                                                       | `310-353`                   |
| `GET /__graphify_graph?id=` streamed graph read                                                                         | `355-395`                   |
| `DELETE /__graphify_remove?id=` artifact + registry deletion                                                            | `397-446`                   |
| `POST /__graphify_ingest` endpoint shell/security contract                                                              | `448-464`                   |
| JSON body parse + required path handling                                                                                | `465-489`                   |
| Git/GitHub URL detection, validation, shallow clone, temp cleanup                                                       | `491-538`                   |
| Local path expansion and existence check                                                                                | `539-547`                   |
| Graphify binary resolution + `execFileSync(bin, ["update", repoPath])`                                                  | `549-563`                   |
| Read generated graph artifact from graphify scratch output                                                              | `564-577`                   |
| Vendored-deps guard, refuses >12,000 nodes                                                                              | `579-599`                   |
| Metadata computation: degree, god nodes, extracted %, communities, language                                             | `600-626`                   |
| Path-aware id generation and collision hash                                                                             | `642-664`                   |
| Graph write + registry entry with `graphPath`                                                                           | `666-697`                   |
| Scratch/temp cleanup and large-graph warning                                                                            | `698-719`                   |
| Hermes OAuth-provider setup false-positive fix (`openai-codex`, `nous`, `copilot`, `github-copilot`, `anthropic-oauth`) | `810-857`                   |
| `POST /__hermes_chat` payload adds `toolsets` and `yolo`                                                                | `953-1019`                  |
| Hermes args append `-t <toolsets>` and `--yolo -s graphify`                                                             | `1084-1092`                 |

Security posture (upstream): graph endpoints are loopback-gated; mutating endpoints are also token-gated with `x-claude-os-token`; graphify/git calls use `execFileSync` with argv arrays; graph ids are sanitized/path-confined. AI OS hardens mutations further with the full admin preflight (see Security And Safety Model above).

OAuth readiness nuance: upstream treats OAuth/subscription-backed Hermes providers (`openai-codex`, `nous`, `copilot`, `github-copilot`, `anthropic-oauth`) as configured when `config.yaml` declares the provider, even without a provider API key in `~/.hermes/.env`. AI OS should port this into the Hermes status/readiness path (`scripts/lib/hermes-dev-bridge.ts`) and keep aggregate scanner parity (`scripts/lib/hermes-scanner.ts`) as needed; this is not the ChatGPT/Codex subscription detector in `scripts/lib/subscription-detection.ts`.

### Frontend Anchors (`v2.4/src/routes/codegraph.tsx`)

| UI/behavior                                                                   | `v2.4/src/routes/codegraph.tsx` lines |
| ----------------------------------------------------------------------------- | ------------------------------------- |
| Route creation and imports                                                    | `1-18`                                |
| Paste-once Hermes shared-brain prompt                                         | `20-38`                               |
| Project state and Hermes status                                               | `53-65`                               |
| Live `/__graphify_list` polling every 8s                                      | `67-95`                               |
| Active graph load via `/__graphify_graph`, bundled fallback                   | `97-134`                              |
| God-node computation from loaded graph                                        | `136-150`                             |
| Click/focus god-node inspector state                                          | `154-163`                             |
| Token/cost savings estimate                                                   | `175-188`                             |
| Starter questions                                                             | `190-199`                             |
| Hermes seed context (graphPath + graphify commands)                           | `201-216`                             |
| Header                                                                        | `218-233`                             |
| Scrollable project gallery                                                    | `235-288`                             |
| Main 3D graph panel                                                           | `290-328`                             |
| "Ask Hermes" chips dispatch `hermes-chat-prefill`                             | `330-356`                             |
| Side rail stats, map confidence, important files, savings, selected node      | `359-505`                             |
| Connect-with-Hermes card placement                                            | `508-516`                             |
| Grounded Hermes chat mount (`seedContext`, `seedLabel`, `seedAccent`, `yolo`) | `521-582`                             |
| `IngestCard` fetches `/__token`, POSTs `/__graphify_ingest`                   | `586-679`                             |
| Mini stat component                                                           | `681-689`                             |
| Copyable connect prompt card                                                  | `691-765`                             |

### Renderer Anchors (`v2.4/src/components/graphify-graph-3d.tsx`)

| UI/behavior                                                                    | `v2.4/src/components/graphify-graph-3d.tsx` lines |
| ------------------------------------------------------------------------------ | ------------------------------------------------- |
| Graphify node/link types                                                       | `3-21`                                            |
| Component props: `embedded`, `maxNodes`, `onSelect`, `onMeta`, `pinnedId`      | `46-62`                                           |
| Dynamic imports for `react-force-graph-3d`, `three`, bloom pass                | `101-116`                                         |
| Resize observer                                                                | `118-125`                                         |
| Degree calc, max-node cap, Full/Core density, god-node marking                 | `127-183`                                         |
| Adjacency and hover/pinned lighting                                            | `185-205`                                         |
| Scene setup: controls, fog, lights, starfield, bloom, auto-orbit               | `207-339`                                         |
| Bloom resize                                                                   | `341-347`                                         |
| Community-cluster force and link force tuning                                  | `349-408`                                         |
| Node fly-to and deferred camera fit                                            | `410-467`                                         |
| Memoized custom node meshes, god halos, pulse                                  | `469-514`                                         |
| ForceGraph render props: labels, link colors, extracted particles, click/hover | `516-564`                                         |
| Full/Core toggle, Pause/Play, capped-node notice, legend                       | `571-620`                                         |

### Hermes Chat Grounding Anchors (`v2.4/src/routes/agents.hermes.tsx`)

| Change                                                   | `v2.4/src/routes/agents.hermes.tsx` lines |
| -------------------------------------------------------- | ----------------------------------------- |
| `ReactNode` type import                                  | `3`                                       |
| `useHermesStatus` export                                 | `956`                                     |
| `HermesChat` export and optional KG props                | `2115-2173`                               |
| `HermesChatActive` prop plumbing                         | `2176-2190`                               |
| `hermes-chat-prefill` listener                           | `2218-2230`                               |
| Invisible seed context prepended only on first turn      | `2421-2427`                               |
| `toolsets` and `yolo` forwarded to `/__hermes_chat`      | `2468-2477`                               |
| Visible "Chatting with X" grounding chip                 | `2634-2649`                               |
| Session-list key changed to `${s.id}-${sidx}`            | `2981-2987`                               |
| Assistant bubble readability and `ChatMarkdown` renderer | `3215-3355`                               |

### Data And Registry Notes

* `v2.4/src/data/graphs/index.json:38` stores a **relative** `graphPath` in the checked-in seed entry; the `V2.5` behavior backfills it to absolute in `v2.4/scripts/setup-graphify-brain.sh:76-86`, and new dashboard ingests write absolute paths at `v2.4/vite.config.ts:683-686`. AI OS will ship the seed entry with a workspace-relative path resolved by the read bridge and write absolute paths on ingest.
* `GET /__graphify_list` prunes entries whose graph artifact is missing or whose local source path no longer exists; entries whose stored source path starts with `git:` or is empty are retained because their durable graph lives in the dashboard graph directory.
* `v2.4/src/data/graphs/claude-os.json` is raw minified graphify JSON: 269 nodes, 229 links, 85 communities, 96% links with `confidence: "EXTRACTED"`. AI OS ships its own self-graph snapshot in the same shape.
* `v2.4/HANDOVER.md:54-56` and `v2.4/GRAPHIFY_HANDOVER.md:44` mention four ingested projects, but the shipped snapshot only contains the `claude-os` registry entry and graph (`v2.4/CHANGELOG.md:51-54` reflects the seed-only decision). AI OS ships seed-only too.

### CSS / Asset Note (now wired, not dormant)

`v2.4/src/styles.css:492-544` adds `kg-*` aurora/statue/constellation animation classes, and `v2.4/src/assets/hermes-art/knowledge-graph/thinker.webp` is the matching asset. Upstream left both dormant (the `v2.4` route uses a simple header at `codegraph.tsx:218-233`). Per the phase decision, AI OS **wires these into a real, functional Knowledge Graph hero header** in Session 05.

### Unchanged Upstream (no port work)

* `v2.4/.claude/` and `v2.4/skills/` are byte-for-byte identical to `v2.3`.
* No files were deleted.
* `bun.lock`, `tsconfig.json`, `eslint.config.js`, `wrangler.jsonc`, `components.json`, and all existing assets/routes/library modules other than the listed files are unchanged.
* The upstream `README.md`/`package.json` version-line removal does not apply: AI OS keeps its own version (`0.1.291` at phase start).
* `src/routeTree.gen.ts` remains generated output. Add route files and let the TanStack router plugin regenerate it; do not hand-edit it.

***

## Session Plan

This plan turns the folded inventory into nine ordered sessions. Each session is self-contained with its own objective, scope, port targets, build steps, and exit criteria, and carries explicit `v2.4` reference anchors. Completing all nine in order delivers the full Knowledge Graph + Shared Brain surface on the AI OS architecture.

### Reference Source Map

Every session carries a **Reference (v2.4)** line pointing at the exact source to mirror. Citations are relative to `v2.4/` = `/home/aiwithapex/projects/claudeos/claude-os-v2.4/`. The three reference files that matter most:

* `v2.4/src/routes/codegraph.tsx` -- the entire Knowledge Graph page behavior (anchors in the Frontend Anchors table above).
* `v2.4/src/components/graphify-graph-3d.tsx` -- the reusable renderer (anchors in the Renderer Anchors table above).
* `v2.4/vite.config.ts` -- all graph endpoints and chat grounding (anchors in the Backend Endpoint Anchors table above).

Where a session has no upstream reference, the capability is AI OS-native plumbing (typed contracts, demo fixtures, bridge registration, tests) marked **Reference (v2.4): none - AI OS-native**.

### Phase Outcome (binary)

`/knowledge-graph` provides the full `v2.4`/`V2.5` Knowledge Graph loop -- seed graph rendering, live admin-gated ingest of local paths and GitHub URLs, registry list with auto-prune, removal, god-node focus, savings estimate, real hero header, and grounded Hermes chat against the active graph -- on top of the AI OS typed, modular, admin-gated, tested architecture, with documentation and end-to-end validation. YES/NO at the end of Session 09.

### Cross-Cutting Guardrails (every session must hold these)

1. The admin gate is never weakened: every mutating endpoint keeps loopback + per-run `X-Claude-OS-Token` + `HERMES_DASHBOARD_ADMIN=1` + non-demo + hook-mediated path.
2. Process spawning uses `execFileSync` argv arrays only -- never shell strings; ids and paths stay confined to the shared graph directory.
3. Typed contracts stay authoritative: new payloads get parsers that reject malformed input; no ad hoc JSON.
4. The renderer stays lazy-loaded with cleanup-first effects; the 3D vendor chunk budget does not regress.
5. graphify stays optional: seed/demo fallback renders and ingest degrades to an explicit disabled state when the binary is absent.
6. State machine stays explicit and tested: idle / loading / success / empty / error / offline / token-failure / demo / admin-disabled / admin-ready.
7. Every affordance ships with unit/component coverage in its own session; responsive/e2e and parity sign-off land in Session 09.

### Session Summaries

* **S26-01 Graph Data Contracts And Seed Fixtures.** Typed graphify node-link graph, registry entry, god nodes, metadata, and savings contracts in `src/lib/knowledge-graph-types.ts` with rejecting parsers; demo fixtures in `src/lib/knowledge-graph-demo-data.ts`; checked-in AI OS self-graph + registry in `src/data/graphs/`. **Reference (v2.4):** `src/components/graphify-graph-3d.tsx:3-21`, `src/data/graphs/index.json`, `src/data/graphs/claude-os.json`.
* **S26-02 Graph Read Bridge And Registry Endpoints.** Loopback-only `scripts/lib/knowledge-graph-dev-bridge.ts` exposing `GET /__graphify_list` (registry read + auto-prune) and `GET /__graphify_graph?id=` (streamed, path-confined, bundled fallback); registered in `vite.config.ts` like the Hermes read bridge. **Reference (v2.4):** `vite.config.ts:302-395` (+ prune 310-353).
* **S26-03 Graph Ingest And Removal Admin Bridge.** Admin-gated `scripts/lib/knowledge-graph-admin-bridge.ts` with `POST /__graphify_ingest` (git/GitHub detect + validate + shallow clone + cleanup, local path expansion, graphify resolution, `execFileSync` argv, vendored-deps guard, >12k node refusal, metadata, path-aware id + collision hash, absolute-path registry write) and `DELETE /__graphify_remove`; full preflight + rejection tests. **Reference (v2.4):** `vite.config.ts:397-446, 448-719`.
* **S26-04 Reusable 3D Code Graph Renderer.** `src/components/knowledge-graph/knowledge-graph-3d.tsx` reusing `src/lib/graph-types.ts` and the Mnemosyne lazy/cleanup pattern: density toggle, god nodes + halos + pulse, community-cluster force, fly-to, bloom/starfield/orbit, capping notice, legend; plus a loader shell. **Reference (v2.4):** `src/components/graphify-graph-3d.tsx` full.
* **S26-05 Read Hook Route Shell And Project Gallery.** `src/hooks/use-knowledge-graph.ts` (8s polling, active load + fallback, god-node compute, savings, Hermes status); thin `src/routes/knowledge-graph.tsx` + page adapter; real wired aurora/statue hero header (`kg-*` CSS + `thinker.webp`); project gallery; 3D panel; side rail stats; sidebar nav; route tree generated by TanStack tooling, not hand-edited. **Reference (v2.4):** `src/routes/codegraph.tsx:53-505`, `src/styles.css:492-544`, `src/assets/hermes-art/knowledge-graph/thinker.webp`, `src/components/app-sidebar.tsx:2,90`.
* **S26-06 Ingest UI Connect Prompt And Starter Chips.** Admin-gated `IngestCard` (`/__token` then `/__graphify_ingest`, local path + GitHub URL, remove action, disabled/demo states); copyable connect-with-Hermes prompt; starter-question chips dispatching `hermes-chat-prefill`; mini stat component. **Reference (v2.4):** `src/routes/codegraph.tsx:20-38, 330-356, 508-516, 586-765`.
* **S26-07 Hermes Chat Grounding And Graph Toolset.** Make Hermes chat reusable and groundable: `seedContext`/`seedLabel`/`seedAccent`/`yolo` props, first-turn invisible seed prefix, `hermes-chat-prefill` listener, grounding chip, `toolsets`/`yolo` forwarded to `/__hermes_chat`; `use-hermes-admin.ts` stream extension and `hermes-admin-bridge.ts` args `-t <toolsets>` and `--yolo -s graphify`; mount grounded chat in the Knowledge Graph page. **Reference (v2.4):** `src/routes/agents.hermes.tsx` (anchors above), `vite.config.ts:953-1019, 1084-1092`, `src/routes/codegraph.tsx:201-216, 521-582`.
* **S26-08 Homepage Surface Shared Brain Scripts OAuth.** Homepage Knowledge Graph section (lazy renderer + seed stats); `scripts/setup-graphify-brain.sh` and `scripts/graph-to-dashboard.sh` AI OS-adapted; Hermes OAuth-provider setup false-positive fix in `scripts/lib/hermes-dev-bridge.ts` with scanner parity in `scripts/lib/hermes-scanner.ts` as needed; `.gitignore` `graphify-out/`. **Reference (v2.4):** `src/routes/index.tsx:100-106, 1495-1550`, `scripts/setup-graphify-brain.sh`, `scripts/graph-to-dashboard.sh`, `vite.config.ts:810-857`, `.gitignore:40-42`.
* **S26-09 Documentation Validation And Release.** Knowledge Graph guide + handover + unlocks roadmap in `docs/`; data-contract and agent-pages updates; `docs/CHANGELOG.md` entry; full test suite; accessibility + security review (admin gate, path confinement, process-spawn safety); responsive/e2e; parity sign-off vs `v2.4`/`V2.5`; release version bump. **Reference (v2.4):** `GRAPHIFY.md`, `GRAPHIFY_HANDOVER.md`, `HANDOVER.md`, `docs/knowledge-graph-unlocks.md`, `CHANGELOG.md`.


---

# 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_26/prd_phase_26.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.