# Folkscale.

> Country-calibrated synthetic consumer market research platform implementing Semantic Similarity Rating (SSR, arXiv:2510.08338). Built for human research teams (Visual Research Studio) and autonomous AI agents (Streamable HTTP MCP & REST/SSE API).

## Quickstart for AI Agents

- **Base URL:** `https://folkscale.com`
- **Live Remote MCP (Streamable HTTP):** `https://folkscale.com/mcp` (and `https://mcp.folkscale.com`)
- **Instant Sandbox API Key:** `POST https://folkscale.com/api/agents/register`
- **API Catalog (RFC 9727):** `https://folkscale.com/.well-known/api-catalog`
- **OAuth / OIDC Discovery:** `https://folkscale.com/.well-known/openid-configuration`
- **OpenAPI 3.1 Spec:** `https://folkscale.com/openapi.json`
- **MCP Discovery Card:** `https://folkscale.com/.well-known/mcp.json`
- **Full Canonical Reference:** `https://folkscale.com/llms-full.txt`
- **Markdown Docs:** `https://folkscale.com/docs.md`

## Core Workflow (3 Deterministic Steps)

1. **Generate a country-calibrated panel** — `POST /api/panels/generate` (or MCP tool `create_panel`) with `{ "countryCode": "US", "size": 50 }` (built-in: `US`, `FI`, `UK`, `DE`, `JP`, `BR`, `IN`, or synthesize any country via `POST /api/countries/synthesize`).
2. **Estimate cost before execution** — `POST /api/estimate-cost` (or MCP tool `estimate_study_cost`) to verify deterministic pricing before running a study.
3. **Run an SSR market study** — `POST /api/studies/run` (SSE) or MCP tool `run_market_study` for calibrated 5-point Likert PMFs, Top-2-Box, Shannon entropy, subgroup cross-tabs, authentic verbatims, Executive Research Brief, and PDF export (`GET /api/studies/:id/pdf`).

## Documentation & Discovery

- [Full Reference (llms-full.txt)](https://folkscale.com/llms-full.txt): Complete API schemas, SSR equations, country blueprints, and MCP tool definitions.
- [API & MCP Docs (Markdown)](https://folkscale.com/docs.md): Clean token-efficient Markdown documentation.
- [OpenAPI 3.1 Schema](https://folkscale.com/openapi.json): Machine-readable REST + SSE endpoint contracts.
- [MCP Server Card](https://folkscale.com/.well-known/mcp.json): Live Streamable HTTP MCP tool registry and invocation schemas.
- [Research Studio (Web UI)](https://folkscale.com/studio): Interactive studio for human researchers and teams.
