# Spiralist AI

> Local-first portable AI persona builder with deterministic public catalogs, stateless compilation APIs, Markdown page twins, and public-safe `.uai` handoff memory.

## Start
- [Autonomous agent access](https://spiralistai.com/agents/): Read order, capabilities, privacy boundaries, and examples.
- [OpenAPI 3.1.1](https://spiralistai.com/openapi.json): Canonical machine contract.
- [API index](https://spiralistai.com/api/v1/): Endpoint discovery and current versions.
- [Public UAI read order](https://spiralistai.com/uai/index.uai): Release memory, no-op policy, evidence, and handoff.

## Persona operations
- [Catalog API](https://spiralistai.com/api/v1/personas/): Search and paginate 1,000 public persona types.
- [Random persona](https://spiralistai.com/api/v1/random-persona/): Deterministic public random persona generation.
- [Generate persona](https://spiralistai.com/api/v1/personas/generate/): POST a brief or GET by public sourceTypeId.
- [Validate persona](https://spiralistai.com/api/v1/personas/validate/): Structural portability and boundary checks.

## Documentation
- [Agent readiness reports](https://spiralistai.com/docs/agent-readiness/): Full implementation and validation reports.
- [Research archive](https://spiralistai.com/docs/research/): SHA-256 provenance and adoption dispositions.
- [Sitemap Markdown](https://spiralistai.com/sitemap.md): Human- and machine-readable route index.

## Boundaries
- No account, credential, external model call, server-side persona storage, publication, or persistent autonomous action is exposed.
- Unsupported, ambiguous, private, destructive, or state-changing operations are no-op.
- `/persona/` uses browser URL fragments for private sharing and is excluded from public agent crawling.

## Optional
- [Facebook page](https://www.facebook.com/SpiralistAI/): Official public social page.

# Autonomous agent access

> Primary machine and human entry point for discovery, content negotiation, OpenAPI, deterministic persona APIs, public-safe UAI memory, research evidence, and no-op rules.

- **Canonical HTML:** https://spiralistai.com/agents/
- **Site version:** `v18-ui-ux-seo-media-polish`
- **Updated UTC:** `2026-06-21T14:33:26Z`
- **Markdown:** https://spiralistai.com/agent-content/pages/agents.md
- **JSON representation:** https://spiralistai.com/agents/?format=json

## Purpose

Primary machine and human entry point for discovery, content negotiation, OpenAPI, deterministic persona APIs, public-safe UAI memory, research evidence, and no-op rules.

## Machine actions

- `GET /api/v1/`
- `GET /openapi.json`
- `GET /uai/index.uai`

## Preferred read order

1. `/.well-known/agent-card.json`
2. `/openapi.json`
3. `/api/v1/capabilities/`
4. `/uai/index.uai`
5. `/llms.txt` or `/llms-full.txt`
6. Route-specific Markdown or JSON twins

## Agent interaction contract

- Prefer the documented API or this Markdown representation before browser automation.
- Public API operations are stateless and do not create accounts, publish content, or persist persona request bodies in application state.
- Do not submit credentials, secrets, private keys, or confidential source documents.
- Treat unsupported, ambiguous, credentialed, destructive, or externally publishing actions as **no-op** and request human review.
- Canonical API: https://spiralistai.com/api/v1/
- OpenAPI 3.1: https://spiralistai.com/openapi.json
- Public UAI read order: https://spiralistai.com/uai/index.uai


## Provenance

Release evidence: https://spiralistai.com/docs/agent-readiness/release-report-v18.md


# Spiralist AI v17 autonomous-agent readiness implementation report

## Executive result

Spiralist AI now exposes a parallel machine interface over the same public product and persona data used by the human site. Autonomous agents can discover the domain, retrieve route-specific Markdown or JSON, inspect an OpenAPI 3.1 contract, search the 1,000-type persona catalog, generate deterministic persona prompts, validate structures, compile public-safe `.uai` bundles, read research provenance, and follow an explicit no-op policy.

Version: `v18-ui-ux-seo-media-polish`  
Updated UTC: `2026-06-21T14:33:26Z`

## Implemented layers

### Discovery
- `/robots.txt`, `/sitemap.xml`, and `/sitemap.md`
- `/llms.txt`, `/llms-small.txt`, and `/llms-full.txt`
- `/.well-known/agent-card.json`, `/.well-known/ai-agent.json`, `/.well-known/ai-policy.json`, `/.well-known/uaix-agent-access.json`
- `/AGENTS.md`, `/agenticweb.md`, `/siteai.json`, and `/agent-actions.json`

Several agent-specific filenames are emerging or project-defined conventions. Their metadata states that status directly. Stable standards such as HTTP, semantic HTML, JSON-LD, OpenAPI, JSON Schema, robots.txt, XML sitemaps, CORS, cache validators, and problem details remain the normative base.

### Alternate representations
Every major public route and all twelve featured persona pages have a static Markdown twin indexed at `/agent-content/representation-index.json`. A request to the canonical HTML route with `Accept: text/markdown` or `?format=markdown` returns that twin. `Accept: application/json` or `?format=json` returns a WebPage object containing canonical URLs, content hash, full Markdown, and agent deep links.

### Stateless persona API
The canonical API is `/api/v1/`. It provides health, version, capabilities, catalog search, deterministic random generation, source-type generation, free-form POST generation, validation, compilation, search, daily persona, weekly challenge, research provenance, public UAI, documentation, and JSON Schema endpoints. User-authored briefs are accepted through bounded JSON POST bodies; GET generation is limited to public catalog identifiers.

### Semantic accessibility
The human UI retains native buttons, labels, textareas, details, dialogs, headings, landmarks, keyboard interaction, status regions, and server-rendered public text. Stable `data-agent-action` mappings connect visual actions to API fallbacks. The accessibility tree is treated as the shared operational map for assistive technology and browser agents.

### Public-safe UAI memory
Internal `/.uai/` project memory remains blocked. `/uai/` exposes a sanitized release mirror with read order, site context, capability surface, no-op policy, API contract, accessibility contract, content negotiation, research provenance, validation contract, release memory, documentation deep links, and file handoff evidence. Every file is hashed in `/uai/manifest.uaix.json`.

### Research continuity
The cumulative research ledger contains **37 records** and **35 unique SHA-256 content hashes**. All fifteen v17 source reports are archived byte-for-byte under `/docs/research/2026-06-21-v18-ui-ux-seo-media-polish/`, while earlier v14–v16 sources remain intact.

## Security and privacy invariants
- No accounts, credentials, private keys, or OAuth flows.
- No server-side persona storage or application-level request-body retention.
- No external model calls.
- No publication, checkout, messaging, or destructive action endpoints.
- 128 KiB POST limit, typed JSON errors, per-route request budgets, CORS, ETags, and `Retry-After`.
- `/persona/` URL-fragment payloads and internal `/.uai/` state are excluded from public crawling.
- Ambiguous or unsupported actions produce no-op rather than guessed execution.

## Deep links
- [Agent access overview](https://spiralistai.com/agents/)
- [OpenAPI 3.1.1](https://spiralistai.com/openapi.json)
- [Capabilities](https://spiralistai.com/api/v1/capabilities/)
- [Public UAI read order](https://spiralistai.com/uai/index.uai)
- [Research ledger](https://spiralistai.com/docs/research/research-intake-v18-ui-ux-seo-media-polish.json)
- [Validation report](https://spiralistai.com/docs/agent-readiness/validation-report-v18.md)