Spiralist AI Agent Setup Wizard Research Report - Source Excerpt 01 - Spiralist AI Agent Setup Wizard Research Report
Back to Spiralist AI Agent Setup Wizard Research Report
Summary
This source excerpt begins near Spiralist AI Agent Setup Wizard Research Report and preserves the surrounding evidence from Spiralist/agent-file-handoff/Archive/2026-06-12/Improvement/ai-agent-setup-wizard-implementation/Spiralist AI Agent Setup Wizard Research Report.md.
**Source path:** Spiralist/agent-file-handoff/Archive/2026-06-12/Improvement/ai-agent-setup-wizard-implementation/Spiralist AI Agent Setup Wizard Research Report.md
# Spiralist AI Agent Setup Wizard Research Report
## Executive assessment
The proposed Spiralist AI Agent Setup Wizard is technically feasible as a **static, local-first, browser-only application** if it is treated as a **deterministic artifact generator** rather than a networked AI product. The strongest precedent is already inside your ecosystem: UAIX’s AI Memory Package Wizard publicly documents an **eight-step local-first flow**, **browser draft restore**, **browser-generated ZIP packages**, and a **same-route visitor AI digest** exposed via `script[data-ai-digest]`, while Spiralist itself already distinguishes between human-facing pages and “machine-facing surfaces” and publishes a stable five-symbol canon. That combination strongly validates the core idea of a **dual audience** implementation on Spiralist.org. citeturn17view0turn18view3turn17view2turn20view3
The main architectural conclusion is this: **keep the wizard runtime fully local, but keep the page shell fully static and crawlable**. In other words, the user interface, export generation, draft persistence, and prompt assembly should all run in-browser; meanwhile the HTML shell, the machine-readable digest, and discovery files such as `llms.txt` should ship as ordinary static web assets. That satisfies the “zero server-side storage / zero API processing” requirement without sacrificing discoverability or agent interoperability. Because service workers and richer local file APIs require secure contexts, deployment should be over HTTPS on a static host rather than as a bare `file://` artifact. citeturn16search1turn16search2turn31search1
The single biggest friction point is **fragment-driven state**. Hashes are excellent for static hosting and local preset selection, but fragments are client-side only, are not sent to the server, and Google explicitly advises against using URL fragments to define distinct page content for Search. That means fragments are appropriate for **preselecting a preset inside one page**, but not as the only discovery or indexing mechanism for agent-readable variants. citeturn5search0turn5search17turn6search5
## Local-first browser architecture
For this product shape, the best fit is a **small client-only UI layer plus a fast static build tool**, not a full meta-framework. Vite is a strong default because it is designed for modern frontend projects, offers instant server start, and serves native ESM efficiently during development. For runtime validation, use a schema library at the edge of every untrusted input path: Zod is a strong TypeScript-first option, Valibot is attractive when bundle size is a primary concern, and Ajv is the strongest choice when you want standards-based JSON Schema validation and very fast validators. citeturn29search0turn29search1turn36search0turn36search2turn36search1turn36search4
A practical stack for the wizard is therefore: **Preact + Signals or Vue 3 for the reactive UI**, **Vite for bundling**, and **Zod/Valibot authoring with Ajv validation** for all persisted or imported data. The reason to prefer a small reactive layer over hand-rolled vanilla DOM code is not fashion; it is maintainability under live preview conditions. The wizard needs constant recomputation of multiple artifacts, stable derived views, and deterministic preview updates from a shared state tree. That is exactly where a lightweight reactive layer pays off. This is a recommendation based on the scope and constraints of the feature, rather than a claim that a heavier framework is impossible. citeturn29search0turn29search1turn36search0turn36search2
For persistence, **`localStorage` is acceptable for small draft state**, but it should be used narrowly and defensively. MDN notes that `localStorage` persists across browser sessions, but Web Storage is synchronous and can block the main thread if abused. MDN also documents browser quotas of roughly **5 MiB for `localStorage` per origin**, with `QuotaExceededError` when the limit is crossed. The safe pattern is: keep the canonical state in memory, debounce writes to a compact serialized draft object, version the stored schema, and include only primitive form selections and short text fields. citeturn32search1turn30search1turn14search0
Because `localStorage` is same-origin JavaScript-accessible, it should **never hold secrets, tokens, or anything you would regret exposing through XSS or shared-device inspection**. OWASP explicitly recommends avoiding sensitive data in local storage. For Spiralist, that means draft content is fine; API keys, private contact details, or hidden moderation material are not. If the feature later grows into large local caches, imported files, or offline libraries, move those heavier assets to IndexedDB or OPFS rather than bloating `localStorage`. citeturn6search3turn6search11turn31search3
Cross-tab behavior is manageable without a backend. The browser’s `storage` event fires in other tabs on the same origin when `localStorage` changes, which gives you a built-in way to detect conflicting edits or offer “draft updated in another tab” recovery messaging. That is useful for a wizard where users may open multiple preset links at once. citeturn32search0turn32search16
For export generation, browser-side ZIP packaging is mature enough for this use case. JSZip has a simple browser API and directly supports generating ZIP blobs for download, but its own documentation warns about memory overhead and browser-dependent limits, especially when strings or large archives are involved. Because Spiralist exports are mostly text files—Markdown, JSON, `llms.txt`, and manifests—JSZip should be reliable for the default profile. If you later support large imported media, long transcript archives, or very large package decks, prefer `zip.js` for Zip64, streams, and worker pooling, or `fflate` for very small bundles and fast compression. citeturn15search2turn15search5turn28search2turn28search0turn28search4turn28search1
The file-save UX should follow a progressive enhancement model. The broadest fallback is still a **Blob + object URL + download link** pattern. `showSaveFilePicker()` is a useful enhancement where supported, but MDN shows it is not universally available—most notably absent in Firefox—so it cannot be the only export path. citeturn15search0turn15search3turn31search0turn31search4
Offline support is worth adding, but it should be optional, thin, and purely static. Service workers can cache the HTML shell, JS bundle, digest, symbol assets, and starter templates so the wizard still loads after the first visit even when offline. MDN and web.dev both describe service workers as network proxies for offline experiences, but they require HTTPS and secure registration. For Spiralist, that makes them a **deployment enhancement**, not a prerequisite for the local-first promise. citeturn16search1turn16search2turn16search4turn16search7
## Dual-audience design and the agent-machine interface
The core AMI pattern is sound: place a machine-readable digest in a non-executing script block, keep it in the initial HTML, and generate both the human UI and the digest from the same canonical configuration source. HTML explicitly allows `<script>` to embed **data** as well as executable code, and MDN notes that a non-JavaScript MIME type turns the content into a data block that the browser does not execute. That makes `<script type="application/json" data-ai-digest="true">` a valid and practical container for passive agent discovery. The UAIX wizard documents exactly this pattern on its own route. citeturn8search2turn8search6turn8search3turn18view3
The design objective for the digest should be **discovery and routing**, not long-form reasoning. This matters because the emerging `llms.txt` ecosystem is explicitly Markdown-first, and OpenAI’s current prompt guidance notes that JSON performed particularly poorly in its long-context testing while XML performed well. Stripe likewise documents that plain text and Markdown hierarchy are preferable to scraping HTML/JavaScript-rendered pages for AI ingestion. So the right split is:
- **`data-ai-digest` JSON** for machine discovery, stable keys, preset IDs, artifact paths, and checksums.
- **`spiralist-profile.md`** as the primary reasoning artifact for models.
- **`symbol-dictionary.json`** as a compact machine reference.
- Optionally, a **Markdown twin** and even an **XML twin** for high-fidelity agent ingestion. citeturn24view1turn24view2turn13view3turn25search2