> 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-session02-snapshot-exporter-and-fixtures/spec.md).

# Session Specification

**Session ID**: `phase31-session02-snapshot-exporter-and-fixtures` **Phase**: 31 - Cloudflare Pages Public Demo **Status**: Not Started **Created**: 2026-06-24

***

## 1. Session Overview

This session creates the public-safe snapshot boundary for the hosted AI OS demo. It adds a local-only exporter, committed `/demo/*` fixture assets, a snapshot manifest, and redaction checks so later sessions can switch routes from local bridge reads to frozen browser-safe data.

The work is next because Session 01 already established public-demo mode and static demo-pages output. The app cannot safely disable local reads or render the complete route matrix on Cloudflare Pages until committed fixtures exist and their privacy properties are testable.

The exporter is an authoring tool, not a Cloudflare build step. It may read `src/data/live-data.json` locally when present, but it must project through an allowlist and write only sanitized public fixtures. Pages builds consume the committed `demo-website/public/demo/*` files and must not copy raw local runtime data.

***

## 2. Objectives

1. Create the `demo-website/` fixture boundary without forking the React app or changing the normal Worker deployment path.
2. Add a deterministic local-only snapshot exporter that projects LiveData, Knowledge Graph, Trend Finder, and approved static asset inputs through an allowlist.
3. Commit browser-safe demo fixtures, metadata, and a manifest with capture details, route coverage, input sources, redaction counts, and scan results.
4. Add focused tests and scan logic proving private paths, bridge URLs, auth terms, secrets, prompts, transcripts, command output, memory text, and private labels are removed or rejected.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase31-session01-demo-mode-foundation` - Provides the `VITE_AI_OS_PUBLIC_DEMO` helper, all-extension demo visibility, and verified demo-pages static build branch that later sessions consume.

### Required Tools Or Knowledge

* Bun 1.3.14 project scripts from `package.json`.
* LiveData contracts in `src/lib/live-data-types.ts` and validation in `src/lib/validate-live-data.ts`.
* Knowledge Graph registry and graph parsers in `src/lib/knowledge-graph-types.ts`.
* Trend Finder schema, static Brief privacy helpers, evidence asset manifests, and source-compliance docs.
* Existing script and test layout under `scripts/`, `scripts/lib/__tests__/`, and `scripts/extensions/trend-finder/`.

### Environment Requirements

* Local environment can run Bun scripts, Vitest, TypeScript script typecheck, and file-system writes under the repo.
* No Cloudflare dashboard action, Pages project, credential, billing account, hosted runtime, or external API call is required.
* `src/data/live-data.example.json` is available as the committed fallback when `src/data/live-data.json` is absent or unsuitable for public projection.

***

## 4. Scope

### In Scope (MVP)

* Maintainer can create public demo fixtures locally - Add `scripts/demo/export-pages-snapshot.ts` and `demo:snapshot`.
* Hosted demo can read committed fixtures - Create `demo-website/public/demo/live-data.snapshot.json`, `demo-website/public/demo/graphs/*`, optional `demo-website/public/demo/trend-finder-assets/*`, and `demo-website/public/demo/snapshot-metadata.json`.
* Reviewers can audit what was captured - Add `demo-website/snapshot-manifest.json` with capture time, source commit, exporter version, inputs, redaction counts, route coverage, and scan results.
* Local private data is never copied raw - Project `src/data/live-data.json` or `src/data/live-data.example.json` through an allowlist before writing demo fixtures.
* Snapshot fixtures stay public-safe - Add scanner and tests for local paths, `file://`, loopback and private-LAN URLs, `/__*` bridge URLs, auth terms, token/key-shaped strings, prompts, transcripts, command output, private memory text, and private labels.
* Generated Pages output stays out of git - Add explicit `demo-website/dist/` gitignore coverage even though the repo already has broad `dist` ignore behavior.
* Pages build boundary is documented - `demo-website/README.md` explains that Pages builds consume committed fixtures and do not run `demo:snapshot`.

### Out Of Scope (Deferred)

* Cloudflare Pages static build output and copy strategy - Reason: Session 05 owns `demo:build:pages`, preview, final output assembly, `_headers`, and `_redirects`.
* Route-specific UI conversion from bridge data to `/demo/*` assets - Reason: Sessions 03 and 04 own host routes, mutation guards, extensions, and agent route behavior.
* Running the exporter during Cloudflare builds - Reason: the phase requires committed frozen fixtures for static hosting.
* Publishing raw `src/data/live-data.json` - Reason: local runtime data is private input only and must pass through projection and scan gates.
* New source adapters, hosted collection, scraping, scheduler runs, chat, upload, admin writes, account auth, or remote asset loading - Reason: public demo v1 is static and read-only.

***

## 5. Technical Approach

### Architecture

Create a script library in `scripts/lib/pages-demo-snapshot.ts` that owns input loading, schema validation, projection, privacy scanning, manifest construction, and atomic writes. The CLI in `scripts/demo/export-pages-snapshot.ts` stays thin: parse flags, call the library, print a redacted summary, and return stable exit codes.

LiveData projection starts from `validateLiveData()` so the exporter works with both the generated local file and the committed example. The output allowlist keeps route-populating summary, usage, activity, skills, integrations, automations, knowledge store, memory, local-agent, Hermes, OpenClaw, and extension branches only after bounded projection and redaction. Fields known to hold credential presence, raw paths, raw prompts, transcripts, command output, private notes, source dumps, or local bridge URLs are removed or replaced with demo labels.

Knowledge Graph fixtures use the existing `src/data/graphs/index.json` and `src/data/graphs/*.json` contracts, parsed through `src/lib/knowledge-graph-types.ts` before writing under `demo-website/public/demo/graphs/`. Trend Finder projection uses `src/extensions/trend-finder/schema.ts`, static Brief privacy helpers, source compliance docs, and evidence asset manifest helpers. Any generated Trend Finder field without clear public approval falls back to fixture/demo labels and is recorded in implementation notes.

All writes go through a temporary directory or temporary files and rename into place after scans pass. This keeps reruns idempotent and prevents partially written public fixtures from remaining after a failed projection.

### Design Patterns

* Allowlist-first projection: Public fixtures are built from explicitly approved fields, not from recursive redaction of raw runtime data.
* Script-only runtime boundary: The exporter lives under `scripts/` and is not imported by browser code.
* Parser-backed contracts: Existing LiveData, graph, and Trend Finder parsers validate inputs before projection.
* Atomic fixture writes: Generated public files are staged, scanned, and then renamed into place.
* Manifest as audit trail: The manifest records what was used, what was redacted, and which route families the fixtures are intended to populate.

***

## 6. Deliverables

### Files To Create

| File                                                                                          | Purpose                                                                                         | Est. Lines |
| --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ---------- |
| `scripts/lib/pages-demo-snapshot.ts`                                                          | Snapshot exporter library, projection helpers, scan rules, manifest builder, and atomic writer. | \~450      |
| `scripts/demo/export-pages-snapshot.ts`                                                       | Local-only CLI entrypoint for `bun run demo:snapshot`.                                          | \~150      |
| `scripts/lib/__tests__/pages-demo-snapshot.test.ts`                                           | Focused tests for projection, scanning, manifest, CLI-adjacent behavior, and atomic writes.     | \~260      |
| `demo-website/README.md`                                                                      | Public demo fixture boundary docs and local-only snapshot instructions.                         | \~120      |
| `demo-website/snapshot-manifest.json`                                                         | Committed manifest for the current public demo snapshot.                                        | \~80       |
| `demo-website/public/demo/live-data.snapshot.json`                                            | Committed public-safe LiveData fixture consumed by later demo routes.                           | \~900      |
| `demo-website/public/demo/snapshot-metadata.json`                                             | Small metadata payload for provenance labels and route surfaces.                                | \~80       |
| `demo-website/public/demo/graphs/index.json`                                                  | Public-safe graph registry fixture.                                                             | \~80       |
| `demo-website/public/demo/graphs/ai-os.json`                                                  | Public-safe graph payload fixture.                                                              | \~220      |
| `demo-website/public/demo/trend-finder-assets/README.md`                                      | Placeholder and policy for copied public Trend Finder assets.                                   | \~40       |
| `.spec_system/specs/phase31-session02-snapshot-exporter-and-fixtures/implementation-notes.md` | Session evidence, command outcomes, included fields, and residual risk.                         | \~140      |

### Files To Modify

| File                                                 | Changes                                                                                          | Est. Lines |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ---------- |
| `package.json`                                       | Add `demo:snapshot` script pointing at the local-only exporter.                                  | \~2        |
| `.gitignore`                                         | Add explicit generated-only `demo-website/dist/` ignore coverage.                                | \~4        |
| `scripts/extensions/trend-finder/static-brief-qa.ts` | Export or reuse privacy scan helpers if the exporter needs the extended static Brief scan rules. | \~20       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] `bun run demo:snapshot` writes only `demo-website/public/demo/*`, `demo-website/snapshot-manifest.json`, and expected documentation or metadata files.
* [ ] The exporter validates LiveData input and never copies `src/data/live-data.json` raw into the repo or Pages demo tree.
* [ ] Snapshot metadata and manifest include capture time, source commit, exporter version, input sources used, redaction counts, route coverage, and scan results.
* [ ] Graph fixtures under `demo-website/public/demo/graphs/` parse through the existing Knowledge Graph contracts.
* [ ] Trend Finder fixture output contains only reviewed public fields or explicit fixture/demo fallback labels.
* [ ] The Pages build boundary is documented as committed-fixture consumption, not exporter execution.

### Testing Requirements

* [ ] Unit tests cover allowlist projection, private field rejection, scanner patterns, graph projection, manifest generation, and atomic write failure behavior.
* [ ] Focused exporter tests pass.
* [ ] `bun run typecheck:scripts` passes after adding the script library and CLI.
* [ ] `bun run demo:snapshot` completes and generated fixtures pass the public scan.

### Non-Functional Requirements

* [ ] Snapshot outputs contain no absolute local paths, `file://` URLs, loopback or private-LAN URLs, `/__*` bridge URLs, token/key-shaped strings, raw prompts, transcripts, command output, private memory text, auth state details, or credential-count disclosures.
* [ ] Fixture arrays are bounded and deterministically ordered.
* [ ] No hosted collection, local bridge call, scheduler run, admin write, upload, chat, account-auth flow, Pages Function, analytics, or remote asset loading is introduced.
* [ ] `demo-website/dist/` remains generated-only and ignored.

### Quality Gates

* [ ] All files ASCII-encoded.
* [ ] Unix LF line endings.
* [ ] Code follows project conventions.
* [ ] Public fixtures are product-facing data only; diagnostics remain in tests, manifest scan results, and implementation notes.

***

## 8. Implementation Notes

### Working Assumptions

* `src/data/live-data.example.json` is the reliable fallback input: `.gitignore` marks `src/data/live-data.json` as generated private data, while the committed example is the sanitized template. Planning can proceed because the exporter can prefer local generated input only after allowlist projection and privacy scans, then fall back to the example if needed.
* Trend Finder generated data must default to conservative projection: `docs/sources/source-compliance-*.md`, the Trend Finder schema, and static Brief privacy helpers define public-safe fields, while the Session 02 stub requires unreviewed fields to fall back to fixture/demo labels. Planning can proceed because implementation can record inclusion decisions and avoid publishing unclear fields.
* `demo-website/dist` already appears ignored by the repo's broad `dist` pattern, but this session should add explicit `demo-website/dist/` coverage: the Session 02 stub calls for generated-only coverage and explicit intent helps future reviewers.

### Conflict Resolutions

* `session_02_snapshot_exporter_and_fixtures.md` shows a target tree containing `public/_headers` and `public/_redirects`, while `session_05_pages_build_and_deployment_scaffold.md` explicitly owns adding those files. Session 05 wins for `_headers` and `_redirects`; this session creates `demo-website/`, `public/demo/*`, metadata, manifest, and docs only.

### Key Considerations

* Use the Session 01 public-demo helper as a consumer signal, but keep exporter execution local-only and script-only.
* Keep the snapshot small enough to populate routes and test behavior without committing private runtime payloads or oversized media.
* Preserve existing Worker deployment files and root `wrangler.jsonc`.
* Treat route data consumption as a later step; this session produces the files routes will read.

### Potential Challenges

* Generated local data may include real operator paths or private labels: default to allowlist projection, bounded demo replacements, and hard scan failures before write.
* Trend Finder public field selection spans several prior phases: use existing static Brief QA, source-compliance docs, and schema labels instead of copying arbitrary run output.
* Fixture regeneration can be partially written if interrupted: stage writes and rename only after validation and scan success.

### Relevant Considerations

* \[P00] **Stack conventions**: Bun, Vite 8, TanStack Start, React 19, and Cloudflare Worker compatibility remain baseline constraints.
* \[P02] **Extension payloads and labels stay bounded**: Snapshot output must retain explicit fixture, fallback, degraded, blocked, and unavailable labels.
* \[P05] **Script-only runtime boundary**: Auth, transport, analyst, scoring, snapshot, and source helpers stay under `scripts/`.
* \[P24] **Browser-safe export and triage boundaries**: Local triage notes, private paths, and raw evidence must stay out of exported or browser-visible output.
* \[P26] **Knowledge Graph contract alignment**: Graph fixtures must preserve the parser-backed graph contract used by routes and Hermes grounding.
* \[P30] **AI Rogue default enablement deferred**: Public demo fixture data must not imply normal AI Rogue default enablement outside public-demo mode.

### Behavioral Quality Focus

Checklist active: Yes Top behavioral risks for this session:

* The exporter accidentally publishes raw generated LiveData instead of a bounded public projection.
* Private strings pass because scanner coverage is narrower than the phase privacy requirements.
* Fixture writes leave a partial public demo tree after a failed scan or interrupted run.

***

## 9. Testing Strategy

### Unit Tests

* Test LiveData projection keeps required top-level shape while removing private paths, auth details, prompts, transcripts, command output, and bridge URLs.
* Test scan rules catch `/home/*`, `/Users/*`, `file://`, loopback URLs, private-LAN URLs, `/__*`, bearer tokens, `sk-*`, JWT-like strings, `.env` labels, raw prompt fields, transcript fields, and command output fields.
* Test graph registry and graph payload projection parse through Knowledge Graph contract helpers.
* Test manifest generation includes capture time, source commit, exporter version, input source labels, redaction counts, route coverage, and scan results.
* Test atomic write cleanup when a staged fixture fails the privacy scan.

### Integration Tests

* Run focused Vitest suite for `scripts/lib/pages-demo-snapshot.ts`.
* Run `bun run typecheck:scripts`.
* Run `bun run demo:snapshot` and verify expected files are created.

### Runtime Verification

* Inspect `demo-website/public/demo/live-data.snapshot.json`, `demo-website/public/demo/graphs/index.json`, `demo-website/public/demo/graphs/ai-os.json`, `demo-website/public/demo/snapshot-metadata.json`, and `demo-website/snapshot-manifest.json` for parseability and scan status.
* Verify `git status --short --ignored demo-website/dist` still treats `demo-website/dist/` as ignored generated output.

### Edge Cases

* `src/data/live-data.json` missing.
* `src/data/live-data.json` present but privacy scan fails.
* Graph registry references a missing graph file.
* Trend Finder extension item absent from LiveData.
* Evidence asset manifest absent or containing unavailable assets.
* Repeated `bun run demo:snapshot` reruns.
* Privacy scanner receives nested arrays, mixed casing, camelCase private field names, and long token-shaped strings.

***

## 10. Dependencies

### Other Sessions

* Depends on: `phase31-session01-demo-mode-foundation`
* Depended by: `phase31-session03-app-data-and-mutation-boundary`, `phase31-session04-extensions-and-agent-routes`, `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-session02-snapshot-exporter-and-fixtures/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.