# ChatStack — Full Reference > Canonical agent-facing reference for ChatStack. Dense, no marketing copy. Source of truth for agents that do not follow the marketing HTML. For interactive schemas see `/openapi.json`. For plugin metadata see `/.well-known/ai-plugin.json`. For capability discovery see `/api/agent`. ## Identity - Name: ChatStack - Canonical origin: `https://www.chatstack.app` - Operator: App Developer Studio - Product category: AI PRD generator + software cost estimator - Target users: founders, product managers, and engineers using AI coding tools (Cursor, Claude Code, Windsurf, MCP-aware IDEs) ## Product summary ChatStack converts an unstructured project brief into four structured JSON artifacts plus a story-point cost estimate. Human path: chat interview at `/`. Skip-interview: `POST /api/agent/submit` (`AGENT_API_KEY`). After a PRD is in the portal: personal access token + CRM agent REST (read/write) and/or portal `@chatstack/mcp`. Public interview without a portal account: hosted interview MCP (no PAT) or marketing `/api/agent/interview/*` with guest `interview_token` or PAT. ## Services (marketing) Canonical pages: `/ai-development-services` and `/ai-development-services.md`. Operator delivery: App Developer Studio. 1. PRD creation (free) — 4-agent interview → structured JSON PRD + estimate. Also the Estimate/Planning layer of the ADS playbook. 2. Requirements as a Service — portal, exports, `@chatstack/mcp`, versioned enhancements. 3. Consulting (hourly) — product/engineering workshops (Cursor Plan Mode, project rules, Atlassian MCP ↔ Jira); enterprise AI consulting pointed at `https://www.appdeveloperstudio.co.za/services/ai-consulting`. 4. Full-service design and development (fixed cost) — ADS nine-phase AI-accelerated playbook from the ChatStack PRD: Estimate → Design → Planning → Project management → Development → Observability & testing → Bug reporting → Deployment → Maintenance. Over 95% of ADS's own code is AI-assisted. Full playbook: `https://www.appdeveloperstudio.co.za/services/app-development`. About / credentials: `/about` and `/about.md`. ## The 4-agent workflow 1. User Story Agent — elicits persona-driven user stories in the canonical "As a , I want so that " format; emits `stories_json_approved`. 2. Functional and NFR Agent — derives functional requirements (`FR-`), non-functional requirements (`NFR-`), and assumptions (`ASS-`); emits `requirements_json_approved`. 3. Technical Specs Agent — produces architectural decisions per area (Authentication, Database, Frontend, API, Infrastructure, etc.); emits `techspec_json_approved`. 4. Cost Estimate Agent — assigns story points per story, converts to hours and cost, applies the AI efficiency discount; emits `estimate_json`. ## Cost model - `cost_before_discount = story_points * rate_per_point` - `cost_after_discount = cost_before_discount * (1 - ai_efficiency_discount)` - Default `ai_efficiency_discount = 0.65` reflecting empirically measured rework reduction when AI coding tools receive high-fidelity structured PRD context. - `rate_per_point` and `currency` are declared in `estimate_json.meta`. - Totals are aggregated across `rows[]` in `estimate_json.totals`. ## Popular Apps catalog (AEO) - Hub: `https://www.chatstack.app/popular-apps` (Markdown: `/popular-apps.md`) - Detail: `/popular-apps/` — full public PRD on ChatStack (what's included, line-item cost breakdown, user stories, requirements, tech specs, FAQs); PDF at `/downloads/.pdf` - Year 0–5 TCO calculator on the hub (`#calculator`): default MAU Years 1–5 = 500, 2000, 5000, 10000, 25000; retainer $1500/mo; hosting bands with 10% uplift (≤1k $88, ≤10k $220, ≤50k $495, ≤200k $1210, ≤1M $3025; >1M contact) - After interview estimate in chat: display-only hosting TCO card titled “Estimated Hosting & 5-year Total Cost of Ownership” — Year 0 = visitor `our_estimate_cost_usd`; Years 1–5 use the same default MAU assumptions and bands as the hub calculator; no deep link to the calculator - Caveats (planning, not a fixed quote): interview-sourced MVP figures change with scope; hosting bands are indicative (typical Supabase-backed stack); retainer is maintenance/minor enhancements only; AI token / payment / premium API fees excluded; custom build from ChatStack → client owns code and IP (no platform lock-in) ## Artifact contract Required for a successful submission: - `artifacts.stories_json_approved` — `{ stories: UserStory[], global_nfr?: string[] }` - `artifacts.requirements_json_approved` — `{ requirements: Requirement[] }` - `interview_summary` — plain-text brief, 20+ characters, ideally 2 to 5 sentences. Strongly recommended: - `artifacts.techspec_json_approved` — `{ specifications: TechSpec[] }` - `artifacts.estimate_json` — `{ meta, rows[], totals, assumptions?, risks? }` Contact fields (used to match or create a portal account when provided): `first_name`, `last_name`, `email`, `country`, `message`. Full JSON schemas are at `https://www.chatstack.app/openapi.json`. Agents must not JSON-stringify nested objects; they must submit JSON objects directly. ## ID conventions - User stories: `US-` (e.g. `US-1`). Sequential, stable across submissions. - Functional requirements: `FR-`. - Non-functional requirements: `NFR-`. - Assumptions: `ASS-`. - Technical specifications: `TS-`. - Estimate rows: `id` matches a user story ID for traceability. ## Agent API (marketing site — skip interview) - Discovery: `GET https://www.chatstack.app/api/agent` → JSON with capabilities, auth model, rate limits, schema URL. - Submit: `POST https://www.chatstack.app/api/agent/submit`. - Auth: `Authorization: Bearer `. Keys via `/speak-to-a-human`. Never put this key in an MCP client config. - Content-Type: `application/json` required. Non-JSON returns HTTP 415. - Max payload: 10 MB. Larger returns HTTP 413. - Rate limit: 5 submissions per hour per IP (HTTP 429 when exceeded). Enterprise keys can have higher limits. - Success: HTTP 200 with `{ ok: true, id, project_id, version_id, warnings? }` (both `project_id` and `version_id` required). - V2 normalize failure: HTTP 422 with `{ ok: false, error: "V2_NORMALIZE_FAILED", details, … }`. - Validation failure: HTTP 400 with `{ error, details }`. Server-to-server only (no browser CORS). Browser UI automation: `/agent-browser.md`. Prefer submit when artifacts already exist; prefer portal token + MCP when coding against an existing PRD. ## Interview API (marketing site — PAT or guest) - Auth: portal personal access token (`cst_…`) **or** guest `interview_token` from unauthenticated `POST .../session`. Not `AGENT_API_KEY`. - `POST /api/agent/interview/session` — no Authorization → guest + `{ thread_id, interview_token, auth_kind: "guest" }`; with PAT → portal-bound thread - `POST /api/agent/interview/turn` → `{ thread_id, input_as_text, interaction_mode? }` → turn JSON + `pending_gate_payload` (optional mode switch persists) - `POST /api/agent/interview/action` → `{ thread_id, action_type, payload? }` - `GET /api/agent/interview/status?thread_id=` - `POST /api/agent/interview/submit-prd` → `{ thread_id }` and/or `artifacts` + contact fields - Rate limits: public/guest traffic is capped per network (daily). 429 body: `{ error: "rate_limit", code, message, retry_after_seconds }` plus `Retry-After` header. Prefer surfacing `message` to humans. - OpenAPI: `/openapi.json` ## Portal agent API and MCP - Portal: `https://www.portal.chatstack.app` · token mint: `/settings/api-access` - Discovery: `GET https://www.portal.chatstack.app/api/agent` - Auth: `Authorization: Bearer ` (owner / company membership only) - Read + write REST under `/api/agent/...` (stories, plan, requirements, techspecs, design, lock/unlock, Improve, Build) - Improve/Build generate: default async **202** + poll GET (`generation` / `phase`). Optional SSE via `{ stream: true }`. Jobs may take several minutes — do not treat silence as failure. - Improve agent catalog on GET improve: `agents[].status` = `available` | `in_development` (reserved keys such as brainstorm / go_to_market are not runnable until portal AI ships) - Journey: interview MCP → `submit_prd` → mint portal PAT → portal MCP. Setup: `/cursor-ai-prd-integration-guide.md` - MCP **portal**: `@chatstack/mcp` with `CHATSTACK_MCP_TOOLSET=crm` (stdio) or hosted `https://chatstack-mcp-uiidp6d6gq-nw.a.run.app/mcp` (staging: `https://chatstack-mcp-staging-uiidp6d6gq-nw.a.run.app/mcp`) with Bearer PAT. Never `AGENT_API_KEY` in MCP config. - MCP **public interview**: staging hosted `https://chatstack-mcp-interview-staging-uiidp6d6gq-nw.a.run.app/mcp` (no PAT); tools `start_session`, `send_turn`, `send_action`, `get_interview_status`, `submit_prd`. Production interview service (`chatstack-mcp-interview`) lands with prod MCP CI. - Version gates (portal parity): Improve generate = working version only (quote refused); Build generate = locked working version; lock/reestimate refuse original quote (v0) ## Integrations - Project rules (e.g. `.cursorrules`): derived from the PRD where the IDE supports them. - MCP: portal PAT + `@chatstack/mcp` (CRM) against the portal agent API; public interview MCP (no PAT) for the interview flow; file export also supported. ## Output formats - JSON (primary, canonical) - Markdown (human-readable render of JSON, per page under `/.md`) - CSV (estimate tables, on request) - `.cursorrules` snippet (derived) ## Privacy and data use Conversation and submission data is stored in Supabase (primarily UK-hosted). The self-hosted ChatKit workflow runs on Google Cloud Run in the UK. Before PRD submission, a session is identified by a visitor cookie, not an account. Relevant text is sent to OpenAI's API for inference only; OpenAI does not use API data to train its models. Retention: until an erasure request (admin@appdeveloperstudio.co.za) or account deletion. Bring-your-own-NDA is supported. Full terms and sub-processor list: `/non-disclosure-and-tcs`. ## Crawler and agent policy - `robots.txt` allows all well-behaved crawlers and LLM training agents on HTML and Markdown. - `Disallow: /api/` except `/api/agent` (public discovery GET). - `POST /api/agent/submit` requires an API key and is not meant for crawling. ## Canonical URLs - Home: `https://www.chatstack.app/` (Markdown: `/index.md`) - Portal: `https://www.portal.chatstack.app/` - Machine-readable: `/index.md`, `/llms.txt`, `/llms-full.txt`, `/agent-browser.md`, `/cursor-ai-prd-integration-guide.md`, `/openapi.json`, `/.well-known/ai-plugin.json`, `/ai-dataset.json`, `/sitemap.xml` - Marketing API: `/api/agent` (GET), `/api/agent/submit` (POST, auth) - Portal read API: `https://www.portal.chatstack.app/api/agent` - Marketing Markdown: allowlisted `/.md` under `public/` (see `.vercelignore`); legal terms stay HTML-only at `/non-disclosure-and-tcs`. ## Glossary - PRD — Product Requirements Document. - Story point — agile unit of relative effort; here translated to hours via `rate_per_point`. - AI efficiency discount — fractional reduction applied to pre-discount cost to reflect productivity gains from structured context. - Vibe coding — AI-assisted coding where human intent is conveyed conversationally; requires strong context discipline. - Context drift — loss of project context across long AI-assisted sessions; mitigated by structured PRDs and MCP.