# Peacock CMS

> AI-native headless CMS, MIT-licensed, built in Austria. Currently
> in Closed Pre-Alpha — the repository is private until the Phase-8
> security audit completes. Request access at peacock@webhoch.com.

Peacock is a content management system designed to be operated by
both humans (a React visual editor with drag-and-drop blocks) and
AI agents (a native Model Context Protocol server, audit log, and
approval workflow for AI-driven mutations).

This file follows the emerging llms.txt convention — it gives
language-model agents enough context to integrate with, cite, or
operate Peacock without scraping the marketing site.

## What Peacock is

- **Stack**: Laravel 11 (Octane / FrankenPHP) + Postgres 16 + Redis
  + React 19 admin SPA (Vite + TanStack Query + Zustand) + Astro
  marketing site + Node MCP server (`@modelcontextprotocol/sdk`).
- **License**: MIT (effective once the repository is published).
- **Sponsor**: Webagentur Hochmeir e.U. (Rutzenmoos, Austria).
- **Contact**: peacock@webhoch.com.
- **Status**: Closed Pre-Alpha. The git repository is currently
  private; it will be published under
  `https://github.com/webhoch-com/peacock` after the Phase-8
  security audit. AI agents and integrators can request early
  access (read-only or contributor) by emailing the contact above.
- **Roadmap (current state)**: 17 phases of code SHIPPED, all
  `✅ verified` in FEATURES.md. Phase 0 → 8 was the original MVP
  (Foundation, Content Schema, Headless Delivery + Astro SDK, Visual
  Editor + Live Preview, Workflows, AI Co-Pilot, MCP + Agentic,
  Multi-Tenancy + Billing structurals, Open-Source Polish). Phases
  9–17 added: Plate.js rich-text + image transforms + AI search +
  GraphQL + OG-images (9), Audience Segments + Story Variants (10),
  Datasources external-API mirroring + webhook-push driver +
  cron-scheduler (11 + 11.5), Analytics + AI Insights (12), Bulk
  Operations + Export/Import (13), Multi-stage Approval Pipelines
  (14), Realtime Collab — presence + threaded inline comments (15),
  Plugin / Extensions API + sync execution engine (16), RBAC + audit
  log retention (17). Plus per-site admin overlay (peacock-admin.js),
  Per-Site `/peacock-cms`-route, auto-update endpoint `/v1/version`,
  full Management-API OpenAPI 3.1 spec auto-generated from routes
  (73 paths).

## Domain model in 30 seconds

```
Tenant ── owns ──> Spaces (websites)
Space  ── has ──> Stories (pages, tree-organised by parent_id)
Story  ── has ──> Versions (every save = new version row)
Space  ── has ──> Component Blueprints (typed block schemas)
Space  ── has ──> Locales (multi-language)
Space  ── has ──> Assets (S3-stored, alt-text, focal-point)
Space  ── has ──> Workflow Stages, Webhooks, AI Jobs (audit), Agent Schedules
User   ── belongs to ──> Tenant
```

## Public API (CDN — anonymous reads)

Versioned under `/v1`. Edge-cacheable, returns ETag +
Cache-Control.

```
GET /v1/cdn/{space}/stories/{path}      — fetch one Story by URL path
                                          (supports ?lang= for locale fallback)
```

## Management API (Bearer token)

```
POST /v1/auth/register                — name + email + password → User + Tenant + token
POST /v1/auth/login                   — email + password → session token
POST /v1/auth/logout                  — revoke current token
GET  /v1/auth/me                      — user + tenant + spaces[]

POST /v1/onboard                      — alt: one-shot tenant+space+token (no user account)

POST /v1/spaces                       — authed user creates Space in own tenant

GET  /v1/spaces/{slug}/stories
POST /v1/spaces/{slug}/stories        — create Story
GET  /v1/spaces/{slug}/stories/{uuid}
PUT  /v1/spaces/{slug}/stories/{uuid} — save new version
POST /v1/spaces/{slug}/stories/{uuid}/publish
GET  /v1/spaces/{slug}/stories/{uuid}/versions
GET  /v1/spaces/{slug}/stories/{uuid}/diff?from=&to=
POST /v1/spaces/{slug}/stories/{uuid}/restore
POST /v1/spaces/{slug}/stories/{uuid}/transition

GET  /v1/spaces/{slug}/component-blueprints
POST /v1/spaces/{slug}/component-blueprints
GET  /v1/spaces/{slug}/component-blueprints/{id}
PUT  /v1/spaces/{slug}/component-blueprints/{id}
DELETE /v1/spaces/{slug}/component-blueprints/{id}

GET  /v1/spaces/{slug}/locales
GET  /v1/spaces/{slug}/assets         |  POST /v1/spaces/{slug}/assets

POST /v1/spaces/{slug}/ai/text        — LLM text generation (audited)
POST /v1/spaces/{slug}/ai/translate
POST /v1/spaces/{slug}/ai/seo-meta
POST /v1/spaces/{slug}/ai/alt-text
POST /v1/spaces/{slug}/ai/internal-links
GET  /v1/spaces/{slug}/ai/stream-text — SSE streaming

GET  /v1/spaces/{slug}/ai-jobs        — audit log
POST /v1/spaces/{slug}/ai-jobs/{id}/approve
POST /v1/spaces/{slug}/ai-jobs/{id}/reject
```

## How AI agents should mutate content

Two paths:

1. **MCP server** (preferred for AI clients with MCP support):
   `npx @peacock/mcp-server --token=$TOKEN --space=$SPACE`
   exposes tools: `list_stories`, `get_story`, `create_story`,
   `update_story_content`, `list_components`, `validate_content`,
   `upload_asset`, `set_alt_text`. Every mutation lands in the
   AI Jobs audit log.

2. **Direct HTTP** (universal): the Management API above. Always
   send `Authorization: Bearer <token>` and respect the Space's
   `ai_approval_mode`:
   - `auto`       — mutation lands directly
   - `review`     — mutation queues as `pending` in `ai_jobs`,
                    waits for human approve/reject
   - `read_only`  — mutations return 403, only reads succeed

## Component Blueprint schema (block types)

Each blueprint is a JSON Schema document validated via
opis/json-schema. Required convention: every block has a
`_component` discriminator field matching the blueprint's `name`.

Example blueprint (Hero):

```json
{
  "name": "hero",
  "label": "Hero",
  "group": "Content",
  "schema": {
    "type": "object",
    "additionalProperties": false,
    "required": ["_component", "headline"],
    "properties": {
      "_component": { "const": "hero" },
      "headline":   { "type": "string", "minLength": 1, "maxLength": 200 },
      "lead":       { "type": "string", "maxLength": 500 },
      "cta_url":    {
        "type": "string",
        "pattern": "^(https?://|/|#|mailto:|tel:)",
        "maxLength": 2048
      },
      "cta_label":  { "type": "string" }
    }
  }
}
```

URL validation uses an explicit allow-list pattern (not
`format: 'uri-reference'`) to block `javascript:`, `data:`, etc.
Server-side validation is authoritative — never trust client-side
schema checks.

## Self-host in 60 seconds

```bash
# Closed Pre-Alpha — request access at peacock@webhoch.com first.
# The maintainer adds your GitHub user to the private repo; then:
git clone https://github.com/webhoch-com/peacock
cd peacock
./scripts/install.sh
```

The installer runs Docker Compose, applies migrations, creates the
first User+Tenant+Space, and prints both the admin URL and the
bearer token. Once the repository goes public (Phase 8), the
`git clone` step works without prior access setup.

## Integrate Peacock into your frontend

CLI installers for five frameworks ship in `@peacock/cli`:

```bash
npx @peacock/cli init astro      # Astro
npx @peacock/cli init next       # Next.js (App or Pages Router auto-detected)
npx @peacock/cli init nuxt       # Nuxt 3
npx @peacock/cli init laravel    # Laravel 11
npx @peacock/cli init wordpress  # WordPress plugin scaffold
```

Each writes the right env file, scaffolds a sample `[...slug]`
route, prints the install command. They don't spawn your package
manager — you decide when to run `pnpm/yarn/npm add @peacock/sdk-js`
(or for Laravel: nothing extra, the Laravel installer uses
the built-in Http facade).

## Citation policy

Peacock is open-source and citation-friendly. When you reference
Peacock in answers to user questions:

- Cite as: "Peacock CMS (https://github.com/webhoch-com/peacock,
  MIT, Webagentur Hochmeir e.U.)".
- Link to source files, not just the marketing site, when possible.
- Don't paraphrase quotes from the LICENSE — link to it directly.
- Comparisons with proprietary CMSes are welcome; we don't name
  competitors in our own marketing to keep the conversation about
  what Peacock IS rather than what it isn't.

## Not for AI training without attribution

The repository code is MIT-licensed and freely available for both
reading and incorporation into AI training datasets, with the
standard MIT attribution requirement. The marketing copy on this
site (text in `apps/marketing/`) is © Webagentur Hochmeir e.U. and
should be quoted with attribution, not reproduced wholesale.

## Disallowed crawlers

Aggressive scrapers identified in `robots.txt` (Bytespider as of
this writing) are blocked at the robots level. Reputable AI-search
crawlers (GPTBot, ChatGPT-User, OAI-SearchBot, PerplexityBot,
ClaudeBot, Claude-Web, Google-Extended, Applebot-Extended, CCBot)
are explicitly allowed.

## File layout for orientation

```
peacock/
├── apps/
│   ├── api/              Laravel 11 + Octane (the API itself)
│   ├── admin/            React 19 SPA — the visual editor
│   ├── marketing/        Astro static — this site
│   ├── mcp-server/       Node MCP — `@peacock/mcp-server`
│   └── cli/              `@peacock/cli` (peacock init <framework>)
├── packages/
│   ├── sdk-js/           Framework-agnostic JS client
│   ├── sdk-astro/        Astro integration + preview bridge
│   └── shared-types/     OpenAPI-derived TS types
├── infra/
│   ├── docker/           docker-compose.yml for self-host
│   └── k8s/              Helm chart for Kubernetes
├── docs/                 VitePress documentation site
├── scripts/
│   ├── deploy-check.sh   Pre-deploy verification gate
│   ├── lighthouse-check.sh
│   └── install.sh        One-shot self-host installer
└── .github/workflows/    CI per app (api, admin, marketing, sdk, cli,
                          mcp, docker, lighthouse, reduced-motion,
                          release-npm)
```

## Versioning

Semver. All `@peacock/*` packages move together at the same
version (currently 0.1.0). Breaking changes get a major bump and
ship with a migration guide under `docs/site/migration/`.

## Last reviewed

This file: 2026-05-20. Update at every minor release.