> 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/phase31-session04-extensions-and-agent-routes/spec.md).

# Session Specification

**Session ID**: `phase31-session04-extensions-and-agent-routes` **Phase**: 31 - Cloudflare Pages Public Demo **Status**: Not Started **Created**: 2026-06-24

***

## 1. Session Overview

This session brings the remaining public demo route families into safe hosted behavior. Sessions 01 through 03 added the public-demo flag, committed snapshot fixtures, frozen LiveData loading, and shared mutation guards. Session 04 now applies that boundary to the deeper agent, Knowledge Graph, Trend Finder, and AI Rogue surfaces that can still mount route-specific hooks or asset loaders.

The session is next because the Pages build scaffold in Session 05 should only package route behavior that is already public-safe. The implementation should reuse existing demo/read-only modes and browser-local AI Rogue persistence instead of forking routes or adding hosted services.

The result is a representative public demo route set where unsafe actions stay visible but disabled, extension and agent surfaces remain reachable, and focused tests prove the planned route families do not request local bridges such as `/__token`, `/__hermes_*`, `/__openclaw_*`, `/__graphify_*`, or Trend Finder bridge endpoints while public-demo mode is active.

***

## 2. Objectives

1. Force Hermes, Claude Code, OpenClaw, and Knowledge Graph routes into demo or read-only hosted behavior in public-demo mode.
2. Make Trend Finder public-demo data labels, visibility settings, and evidence asset previews consume snapshot or static `/demo/*` data without bridge requests.
3. Verify AI Rogue Play, Ledger, Loadout, and Settings remain browser-local and do not imply hosted server state, telemetry, remote loading, or default enablement outside public-demo mode.
4. Add focused route and component tests that assert representative agent, Knowledge Graph, Trend Finder, and AI Rogue paths do not request local bridge endpoints in public-demo mode.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase31-session01-demo-mode-foundation` - Provides `VITE_AI_OS_PUBLIC_DEMO`, shared public-demo helpers, static demo-pages mode, and forced registered extension visibility.
* [x] `phase31-session02-snapshot-exporter-and-fixtures` - Provides `demo-website/public/demo/*` fixtures, graph fixtures, snapshot metadata, and public fixture scanning.
* [x] `phase31-session03-app-data-and-mutation-boundary` - Provides frozen LiveData loading from `/demo/live-data.snapshot.json` and shared mutation guards for setup, refresh, scheduler, source setup, and run controls.

### Required Tools Or Knowledge

* Bun 1.3.14 for focused Vitest and route test commands.
* React Query route hook behavior and existing test helpers under `src/routes/__tests__/`.
* Existing demo fixture helpers in `src/lib/hermes-demo-data.ts`, `src/lib/openclaw-demo-data.ts`, and `src/lib/knowledge-graph-demo-data.ts`.

### Environment Requirements

* No network or third-party service is required.
* Public demo behavior is activated with `VITE_AI_OS_PUBLIC_DEMO=1`.
* Generated Pages output remains out of scope for this session; Session 05 owns `demo-website/dist`.

***

## 4. Scope

### In Scope (MVP)

* Public visitors can open Hermes, Claude Code, and OpenClaw agent routes without live bridge reads or admin writes - force existing demo/sample data in hosted public-demo mode and hide or disable live toggles.
* Public visitors can open Knowledge Graph without `graphify` bridge reads or admin writes - force the existing demo fixture graph and demo admin state.
* Public visitors can open Trend Finder routes from frozen snapshot or fixture data - keep provenance labels explicit and avoid visibility, source setup, scheduler, run, Creator Lens, and asset bridge requests.
* Public visitors can view Trend Finder evidence assets only through reviewed static `/demo/trend-finder-assets/*` URLs or unavailable states - no `/__trend_finder_asset/*` or `/__token` request is allowed in public-demo mode.
* Public visitors can open AI Rogue Play, Ledger, Loadout, and Settings with committed bundled assets and browser-local localStorage/IndexedDB state - copy and status labels must not imply hosted server persistence or normal default enablement.
* Developers get focused public-demo tests that fail if representative routes request any local bridge endpoint.

### Out Of Scope (Deferred)

* Cloudflare Pages build, preview, `_headers`, `_redirects`, and deployment documentation - Reason: Session 05 owns the Pages deployment scaffold.
* Full static preview route matrix and generated-output privacy scan - Reason: Session 06 owns broad QA and privacy verification.
* New source adapters, hosted collectors, schedulers, or public source compliance decisions - Reason: Phase 31 v1 is static-only.
* Default AI Rogue enablement outside public-demo mode - Reason: P30 explicitly keeps default enablement deferred.
* Pages Functions, advanced `_worker.js`, analytics, uploads, chat writes, or admin writes - Reason: Phase 31 v1 is a static read-only public demo.

***

## 5. Technical Approach

### Architecture

Keep the public-demo boundary inside the existing route tree. Do not fork the React app and do not introduce a second demo route implementation. Route components should use `isBrowserPublicDemoMode()` from `src/lib/public-demo.ts` to coerce their existing `demoMode` flags before live React Query hooks can construct bridge URLs. This matches the Session 03 pattern of guarding before URL construction.

Hermes, Claude Code, and OpenClaw already have local demo/sample data paths. Public-demo mode should select those paths automatically, reset selected live session state on entry, and remove or disable "return to live" affordances while hosted. Knowledge Graph already supports a demo fixture path in `useKnowledgeGraph`; the route/page layer should pass the public-demo flag so registry, graph, token, admin, and grounded chat behavior stay demo-only.

Trend Finder should continue to parse browser-safe data through its schema and view model. Evidence asset handling needs a narrow static path allowlist: `/demo/trend-finder-assets/*` is valid public demo media, while local bridge asset URLs remain unavailable in public-demo mode. Visibility settings should hydrate from localStorage and skip the file bridge endpoint in hosted demo.

AI Rogue should continue using bundled imported assets, localStorage, and IndexedDB. Public-demo copy should describe browser-local persistence and avoid presenting LiveData refresh or Insight Shards claims as hosted server writes. This session should verify behavior with tests rather than adding a new server or storage abstraction.

### Design Patterns

* Route-level public-demo coercion: Ensures unsafe hooks never start live bridge queries before UI guards render.
* Existing demo fixture reuse: Keeps Hermes, OpenClaw, and Knowledge Graph behavior consistent with validated demo/sample contracts.
* Allowlist-first static asset URL handling: Limits Trend Finder media previews to committed `/demo/trend-finder-assets/*` assets in hosted mode.
* Browser-local state labels: Makes AI Rogue persistence understandable without implying hosted collection or server storage.
* Focused no-bridge route tests: Catches regressions before broader Session 06 Playwright coverage.

***

## 6. Deliverables

### Files To Create

| File                                                                               | Purpose                                                                                               | Est. Lines |
| ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ---------- |
| `src/routes/__tests__/public-demo-routes.test.tsx`                                 | Focused route-level no-bridge coverage for agent, Knowledge Graph, Trend Finder, and AI Rogue routes. | \~260      |
| `src/extensions/trend-finder/components/__tests__/evidence-asset-preview.test.tsx` | Static `/demo/trend-finder-assets/*` rendering and public-demo no-token tests for evidence assets.    | \~120      |

### Files To Modify

| File                                                                | Changes                                                                                                        | Est. Lines |
| ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ---------- |
| `src/lib/public-demo.ts`                                            | Add any missing public-demo copy keys for route-level hosted demo states.                                      | \~25       |
| `src/components/hermes/hermes-read-only-page.tsx`                   | Force hosted public-demo sample data, reset session state, and suppress live-mode toggles in public-demo mode. | \~55       |
| `src/components/hermes/claude-code-mission-page.tsx`                | Force Claude Code hosted demo behavior and keep mission actions read-only before admin bridge hooks can write. | \~45       |
| `src/components/openclaw/openclaw-read-only-page.tsx`               | Force OpenClaw hosted demo behavior and keep admin/status/actions demo-only.                                   | \~45       |
| `src/components/knowledge-graph/knowledge-graph-page.tsx`           | Pass public-demo mode into Knowledge Graph read, token, admin, and grounded chat paths.                        | \~25       |
| `src/components/knowledge-graph/knowledge-graph-grounded-chat.tsx`  | Ensure grounded Hermes chat stays demo/read-only when Knowledge Graph is in public-demo mode.                  | \~25       |
| `src/extensions/trend-finder/schema.ts`                             | Allow only static `/demo/trend-finder-assets/*` asset URLs in addition to existing local bridge URLs.          | \~20       |
| `src/extensions/trend-finder/view-model.ts`                         | Distinguish static public asset URLs from local bridge URLs and surface explicit fallback labels.              | \~40       |
| `src/extensions/trend-finder/components/evidence-asset-preview.tsx` | Render static public asset URLs directly and skip token/local bridge fetches in public-demo mode.              | \~70       |
| `src/extensions/trend-finder/use-visibility-settings.ts`            | Skip `TREND_FINDER_VISIBILITY_CONFIG_ENDPOINT` in public-demo mode and keep browser-local visibility settings. | \~35       |
| `src/extensions/trend-finder/views/trends-view.tsx`                 | Ensure public-demo/frozen snapshot labels remain product-facing on the primary Trend Finder route.             | \~25       |
| `src/extensions/trend-finder/views/sources-view.tsx`                | Keep source setup and scheduler sections snapshot/read-only with public-demo provenance copy.                  | \~35       |
| `src/extensions/trend-finder/views/engine-replay-view.tsx`          | Ensure Engine Replay labels sanitized fixture or snapshot traces without raw log or bridge implications.       | \~25       |
| `src/extensions/ai-rogue/views/view-shell.tsx`                      | Add browser-local public-demo status copy and disable any misleading hosted refresh/action language.           | \~35       |
| `src/extensions/ai-rogue/views/play-view.tsx`                       | Verify Play route uses bundled assets and browser-local saves with hosted public-demo copy.                    | \~30       |
| `src/extensions/ai-rogue/views/ledger-view.tsx`                     | Clarify browser-local claim state in public-demo mode and keep duplicate-trigger protection.                   | \~30       |
| `src/routes/__tests__/agents.test.tsx`                              | Extend existing agent route tests for public-demo forced demo mode and no bridge calls.                        | \~80       |
| `src/routes/__tests__/knowledge-graph.test.tsx`                     | Extend Knowledge Graph route tests for public-demo demo fixture behavior.                                      | \~50       |
| `src/routes/__tests__/extensions-routes.test.tsx`                   | Extend extension route tests for public-demo Trend Finder and AI Rogue behavior.                               | \~90       |
| `src/extensions/ai-rogue/__tests__/client.test.tsx`                 | Add public-demo browser-local extension visibility and no-bridge assertions.                                   | \~70       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] Hermes route renders public sample data in public-demo mode and makes no `/__hermes_*`, `/__token`, chat, upload, mission, document, file-preview, Pantheon, or Obsidian bridge request.
* [ ] Claude Code route renders read-only sample mission data in public-demo mode without Claude-specific spawn, shell, git, workspace, Hermes admin, or mission write requests.
* [ ] OpenClaw route renders demo data in public-demo mode and makes no `/__openclaw_*`, `/__token`, dashboard, or admin-action request.
* [ ] Knowledge Graph route renders demo graph fixtures in public-demo mode and makes no `/__graphify_*`, `/__token`, ingest, remove, or Hermes chat request.
* [ ] Trend Finder routes render frozen snapshot, fixture/demo, deterministic fallback, unavailable, and redacted generated source labels as appropriate.
* [ ] Trend Finder evidence assets render only reviewed static `/demo/trend-finder-assets/*` assets or unavailable states in public-demo mode.
* [ ] AI Rogue Play, Ledger, Loadout, and Settings remain visible and browser-local in public-demo mode with no bridge, remote loader, server state, or private telemetry call.

### Testing Requirements

* [ ] Focused public-demo route tests written and passing.
* [ ] Focused Trend Finder asset preview tests written and passing.
* [ ] Existing agent, Knowledge Graph, extension, and AI Rogue route/component tests updated where behavior changes.
* [ ] Focused test commands run and recorded in implementation notes.

### Non-Functional Requirements

* [ ] Public-demo route guards run before local bridge URLs or token requests are constructed.
* [ ] Public-demo copy remains product-facing and does not expose diagnostic endpoint names in normal UI surfaces.
* [ ] Public asset URL handling is allowlist-first and rejects arbitrary local, loopback, private-LAN, bridge, or remote URLs.
* [ ] AI Rogue keeps route-lazy runtime ownership and does not increase the public demo beyond browser-local storage and bundled assets.

### Quality Gates

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

***

## 8. Implementation Notes

### Working Assumptions

* Public-demo coercion belongs at the route/page boundary: Existing Hermes, Claude Code, OpenClaw, and Knowledge Graph components already accept demo state or pass it to hooks; forcing that state at mount prevents bridge queries before child controls render.
* Trend Finder static assets should use `/demo/trend-finder-assets/*`: The Phase 31 PRD defines this directory as the reviewed public media boundary, and `demo-website/public/demo/trend-finder-assets/README.md` already documents the asset policy.
* Focused route and component tests are enough for this session: Session 04 requires representative route tests, while Session 06 owns the full Pages static preview matrix and generated-output privacy scan.

### Conflict Resolutions

* Master PRD phase table still lists Phase 31 as `Not Started`, while the analyzer output, Phase 31 PRD progress tracker, and completed session summaries show Sessions 01 through 03 complete and Phase 31 in progress. The analyzer output is authoritative for workflow state, and the session summaries provide concrete completion evidence, so Session 04 is the next executable session.

### Key Considerations

* Guard before URL construction, not only before button click handlers.
* Reuse existing demo data and route shells instead of creating a forked public app.
* Keep hosted public-demo copy clear without naming internal endpoints in normal user-facing states.
* Preserve the existing Worker deployment and local dev bridge behavior outside public-demo mode.

### Potential Challenges

* Deep child components may start bridge queries through shared hooks: Mitigation is route/page coercion plus focused tests that spy on all fetch requests.
* Trend Finder asset URLs currently only accept local bridge paths: Mitigation is a narrow schema/view-model split for static public assets and local bridge assets.
* AI Rogue depends on LiveData for economy/progression while using browser-local persistence: Mitigation is to let public-demo LiveData come from the committed snapshot and label persistence as browser-local.

### Relevant Considerations

* \[P02] **Extension payloads and labels stay bounded**: Public demo labels must distinguish live, fixture, fallback, degraded, restricted, and unavailable states.
* \[P02] **Static extension registry requires code changes**: Extension visibility stays compile-time and public-demo enabled through the existing registry.
* \[P21] **Claude OAuth material stays script-only**: Agent routes must not expose token, account, bearer, or OAuth material in browser state.
* \[P24] **Browser-safe export and triage boundaries**: Trend Finder assets and Brief content must remain browser-safe projections.
* \[P26] **Knowledge Graph contract alignment**: Public graph snapshots, route UI, and demo fixtures must continue using the shared graph parser contracts.
* \[P30] **AI Rogue default enablement deferred**: Public demo visibility must not imply normal default enablement outside hosted demo mode.

### Behavioral Quality Focus

Checklist active: Yes Top behavioral risks for this session:

* A route can construct or issue a local bridge request before the hosted demo disabled state renders.
* Static asset handling can accidentally allow arbitrary local, bridge, or remote URLs in public-demo mode.
* Browser-local AI Rogue state can be mislabeled as hosted/server state or can allow duplicate mutation triggers while saving or claiming.

***

## 9. Testing Strategy

### Unit Tests

* Extend hook/component tests for public-demo no-fetch behavior in Hermes, OpenClaw, Knowledge Graph, Trend Finder visibility settings, Trend Finder asset previews, and AI Rogue browser-local state.

### Integration Tests

* Add route-level public-demo tests that render representative agent, Knowledge Graph, Trend Finder, and AI Rogue routes with `VITE_AI_OS_PUBLIC_DEMO=1` and assert no request path begins with `/__`.

### Runtime Verification

* Run focused Vitest suites for changed route, hook, component, and extension tests.
* Run `bun run typecheck` after implementation if code changes touch shared route or schema types.

### Edge Cases

* Public-demo route is entered after a live/demo toggle was previously selected.
* Trend Finder asset has a local bridge URL, a static `/demo/*` URL, an empty URL, or an invalid URL.
* Browser is offline during public-demo mode.
* AI Rogue persistence is unavailable, denied, empty, saving, or already claimed while public-demo mode is active.

***

## 10. Dependencies

### Other Sessions

* Depends on: `phase31-session01-demo-mode-foundation`, `phase31-session02-snapshot-exporter-and-fixtures`, `phase31-session03-app-data-and-mutation-boundary`.
* Depended by: `phase31-session05-pages-build-and-deployment-scaffold`, `phase31-session06-demo-qa-and-privacy-verification`, `phase31-session07-release-polish-and-documentation`.

***

## Next Steps

Run the `implement` workflow step to begin implementation.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase31-session04-extensions-and-agent-routes/spec.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.