# Viglet Shio

> An open-source, self-hosted, agent-ready CMS with four ways in, over one content engine:
> a full React console that needs no agent at all (sites, content types, media,
> publishing, users); an MCP + CLI surface built for coding agents; the content
> projected to files for a repository workflow; and REST/GraphQL delivery with
> TypeScript SDKs. Same posts, same drafts, same publish act behind all four.
> Agent-first is the order a capability is built in (law P1), not a condition of use.
> Shio hosts no model and no prompts: it is the substrate an external agent drives.

## Read the Markdown, not the HTML

Every route on this site is also published as Markdown at `<path>.md`: the same content,
converted from the same render, with the navigation and the footer left out. Across the
eleven routes that is 79 KB of Markdown against 587 KB of HTML.

- `/` → https://openviglet.github.io/shio/index.md
- any other route → append `.md`, e.g. https://openviglet.github.io/shio/features/rendering.md
- https://openviglet.github.io/shio/manifest.json: the routes, their twins and their sizes, in the
  shape `/api/v2/agent/manifest` uses

## Pages on this site

- [/](https://openviglet.github.io/shio/): the four ways in, six deployment shapes,
  then one section per design law
- [/console](https://openviglet.github.io/shio/console/): the traditional path in full, with everything
  the React console does on its own, the four capabilities that live on the CLI instead, and
  what changes if an agent is attached later
- [/claude-code](https://openviglet.github.io/shio/claude-code/): install the plugin or the bare MCP
  bridge, the three calls a session opens with, and the AGENT token scope
- [/compare](https://openviglet.github.io/shio/compare/): agent-operability against Contentful,
  Sanity, Strapi and WordPress, plus where each of them wins
- [/replicate](https://openviglet.github.io/shio/replicate/): capture an existing site with shio clone,
  the fidelity-versus-authorable decision, and the bounds the crawl keeps
- [/curator](https://openviglet.github.io/shio/curator/): the curator's half: the review queue, preview
  links, inline editing, and the six gates that stop an agent write
- [/features/agent-gateway](https://openviglet.github.io/shio/features/agent-gateway/): the manifest,
  the context pack, planned batches and teaching errors
- [/features/content-as-files](https://openviglet.github.io/shio/features/content-as-files/): the
  Markdown projection, the field table and the three-way merge
- [/features/blueprints](https://openviglet.github.io/shio/features/blueprints/): the package format
  and the rules that keep it from becoming a third contract
- [/features/rendering](https://openviglet.github.io/shio/features/rendering/): layouts, regions, the
  section vocabulary and design tokens in the W3C DTCG shape
- [/features/delivery](https://openviglet.github.io/shio/features/delivery/): REST, GraphQL, the
  zero-dependency client, the generated Next.js starter and the token scopes

## Start here

- Manifest first. `GET /api/v2/agent/manifest` returns capabilities, limits and a
  curated endpoint index. Unshipped capabilities are reported `false`, never omitted; where a
  capability lives elsewhere, `elsewhere` names the command to use instead.
- Then one call for everything else: `GET /api/v2/agent/context?include=all,manifest,ops`,
  returning the content model, the sitemap, the conventions and the write vocabulary, with a
  digest so a later session can skip re-reading it.

## Attach it to Claude Code

```
claude mcp add shio -- npx @viglet/shio mcp
```

`POST /mcp` speaks JSON-RPC 2.0 (revision 2025-06-18). `GET /mcp` is a deliberate 405:
this server sends nothing unprompted.

## MCP tools

`shio_context` · `shio_find` · `shio_read` · `shio_write` · `shio_apply` ·
`shio_publish` · `shio_assets` · `shio_changes` · `shio_verify` · `shio_digest` ·
`shio_remember` · `shio_marketplace`

## MCP resources

`shio://manifest` · `shio://context` · `shio://ops` · `shio://blueprints` ·
`shio://schema/{postType}` · `shio://blueprint/{name}`

## Endpoints an agent uses

- `GET /api/v2/agent/manifest`: capabilities, limits, a curated endpoint index
- `GET /api/v2/agent/context`: model, sitemap, conventions, write vocabulary, digest
- `GET /api/v2/agent/find` · `GET /api/v2/agent/read`: search and read
- `POST /api/v2/agent/batch`: the write vocabulary; `dryRun` plans instead of applying
- `GET /api/v2/agent/verify` · `GET /api/v2/agent/render`: the lint and the render digest
- `GET /api/v2/agent/changes` · `GET /api/v2/agent/diagnostics` · `/api/v2/agent/memory`
- `GET /api/v2/cda/**`: the delivery API; `POST /api/graphql` for the GraphQL shape
- `POST /mcp`: the same capabilities over MCP

## Addresses

- `post:<site>/<friendly-url>` is a post. A site's home page is `post:<site>/`.
- `folder:<site>/<name-chain>` is a folder, by the names the console shows, never by id.
- `site:<name>` is the site itself.
- `id:<uuid>` reads only. Writes take `post:` and `folder:` alone.

## CLI (@viglet/shio)

`shio init` · `shio pull|push [--content]` · `shio apply [--check|--blueprint]` ·
`shio verify [--delivery|--strict]` · `shio digest` · `shio audit <page>` ·
`shio snapshot <page>` · `shio clone <url>` · `shio changes` · `shio report` ·
`shio remember` · `shio mcp` · `shio dev` · `shio deploy`

## Packages

- `@viglet/shio`: the CLI, and the MCP stdio bridge
- `@viglet/shio-client`: framework-agnostic delivery client, zero runtime dependencies
- `@viglet/shio-react-sdk`: hooks and render components over that core
- `@viglet/shio-sections`: the page-section vocabulary shared by agent, console and front end
- `@viglet/create-shio-app`: generates a Next.js App Router site wired to a site's content
- `@viglet/shio-editor-cors`: the Universal Editor bridge for inline editing

## The ten design laws

A feature that breaks one is wrong even if it was requested.

- P1 Agent-first design order: every capability lands MCP → files/CLI → REST → console.
  It orders how a capability ships, never who may operate the CMS: the console is a full
  CMS on its own, and an instance with no agent token issued is an ordinary CMS.
- P2 One call replaces a session: discovery is a product feature, not a docs problem.
- P3 Tokens are a measured budget: a token regression fails the build.
- P4 Files beat APIs for authoring: Edit, Write and Grep are the cheapest tools.
- P5 Determinism over cleverness: stable ordering, path addressing, idempotent writes.
- P6 Errors are instructions: every 4xx carries fix, allowed, didYouMean, example.
- P7 Never surprise the curator: draft-default, dry-run, explicit publish, confirm tokens.
- P8 Skipping steps needs appliable units: blueprints, not prose recipes.
- P9 Close the perception loop: cheap textual proof instead of asking someone to look.
- P10 Compose, don't fork: MCP is a shape over the delivery API, never a third contract.

## Links

- Documentation: https://openviglet.github.io/shio/docs/
- Source: https://github.com/openviglet/shio
- The design laws: https://github.com/openviglet/shio/blob/HEAD/agents.md
- The concept spec: https://github.com/openviglet/shio/blob/HEAD/docs/specs/SH74-agent-native-cms.md
- Roadmap: https://github.com/openviglet/shio/blob/HEAD/docs/ROADMAP.md
- Viglet Turing, the sibling enterprise search product: https://turing.viglet.org