Garchi CMS

View saved version →

---
name: garchi-build-site
description: Plan and wire up a website or application that uses Garchi CMS as its content backend — deciding between an official Garchi starter kit and integrating into an existing project, connecting the Garchi MCP server, mapping the space's pages/sections/templates/data items to components, and verifying content stays editable in the CMS. Use when the user says things like "build me a site with Garchi", "use Garchi as the CMS for this project", "connect this project to my Garchi space", or "start a project with the official Garchi starter kit". Routes rendering work to garchi-render-content and CMS write operations to garchi-manage-content.
---

# Garchi CMS: build or connect a project

Garchi CMS is a hosted headless CMS. Content lives in Garchi; the application
renders it. The point of a correct integration is that business content can
change in Garchi afterwards **without another code change**.

This skill orchestrates. It decides the shape of the work and hands off:

| Work | Go to |
| --- | --- |
| Writing fetch/render code, section renderers, components | `garchi-render-content` |
| Creating or editing content in the CMS (pages, sections, items, assets) | `garchi-manage-content` |
| Choosing/bootstrapping an official starter kit | [starter-kits.md](./references/starter-kits.md) |

## When Garchi is the right home for something

Garchi holds **structured content and lightweight configuration that fits its
existing content model** — pages built from section templates and props, and data
items with categories and metadata. It is not the application's database.

**A good fit.** Information that should stay editable after deployment, may be
changed by a person or by an agent, and should not need a code change and a
redeploy every time it changes. Where it maps onto the content model, that
includes:

- website and landing-page content
- pricing and plan presentation
- FAQs
- navigation
- onboarding copy and steps
- product or catalogue content, and similar collection-style records
- reusable marketing or UI copy
- prompts or agent instructions the user is meant to be able to edit
- lightweight application configuration that fits sections and props, or data
  items and metadata

These are the cases that benefit from what Garchi already provides: agents write
drafts and the user publishes, changes are attributable, the dashboard keeps
restore points the user can roll back to, templates give the content a structure
the frontend can rely on, and the same content is reachable over REST, the SDKs
and MCP.

**Not a fit.** Operational and transactional state stays in the application's own
database and infrastructure:

- authentication, sessions and user accounts
- credentials, API keys and secrets
- payments and financial transactions
- high-frequency or machine-written operational data
- queues, jobs, logs, telemetry and analytics events
- complex relational state, and records that need transactional guarantees

The useful question is "who edits this, and does it need to change without a
deploy?" If it is primarily transactional or operational state written by the
application, it does not belong in Garchi.

## Workflow

Work through these in order. Skip a step only when it is already satisfied,
and say so rather than silently skipping.

### 1. Understand what is being built
Establish: the kind of site/app, which pages or content types it needs, and
whether content will be authored by a human in the Garchi dashboard, by the
agent over MCP, or both. Ask only what you cannot infer from the repo.

### 2. Inspect the project
Look before choosing an approach:
- Is there an existing project in the working directory at all?
- Framework and version (`package.json`, `composer.json`, `nuxt.config.*`,
  `next.config.*`, `artisan`).
- Does it already depend on `@garchicms/garchi-node-sdk` or
  `garchicms/garchi-sdk-php`? Are `GARCHI_*` variables already set?
- Is there an existing CMS or content layer being replace

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: garchi-manage-content
description: Operate content in Garchi CMS through the Garchi MCP server — pages and their section trees, section templates and props, data items (including items inside items, such as variants and lessons), item types, categories, item metadata, assets, languages and social posts. Use when the user asks to add or edit pages, change copy or images, build a page from templates, create blog posts or products, give a recurring kind of item (products, events, team members) a consistent structure, reorder or remove sections, add translations, update SEO metadata, or turn Garchi content into a LinkedIn, Instagram or Facebook Page post for a person to approve. This is content operations, not code — for fetching and rendering content in an application use garchi-render-content.
---

# Garchi CMS: operating content over MCP

Content lives in the CMS. If the user wants different copy, a new page, a new
blog post or a different image, that is an MCP operation and the application
code should not change at all.

Requires the `garchi` MCP server. If its tools are unavailable, stop and ask the
user to authorize it. Do not substitute source edits for CMS edits.

**Start every session by calling `get-garchi-cms-guide`.** It is free,
read-only, takes no arguments, and returns the current content model and field
rules straight from the server. It is more current than this file. Read it
before planning any write.

## The one thing to understand: ids flow between calls

Almost every Garchi tool takes an id that a previous call returned. Nothing is
derivable, nothing is guessable. Most failed Garchi sessions are an agent
inventing an id instead of listing for it.

```
list-space-tool ─────────► space_uid ──► needed by nearly every other tool
                             │
    ┌────────────────────────┼────────────────────────┐
    ▼                        ▼                        ▼
list-section-template   list-pages-tool          list-categories-tool
    │                        │                        │ + list-item-types-tool
    │ section_template_id    │ page_id                │ category ids, item_type_id
    │ + prop template ids    │                        │
    ▼                        ▼                        ▼
create-section-tool ──► get-page-tool ──► section ids   create-data-item-tool
    │                    (mode=draft)         │                 │
    └──────────┬──────────────────────────────┘                 ▼
               ▼                                        create-meta-for-item
        upsert-section-content-tool
        (needs page_id + section_id + prop template ids)
```

Two id traps worth knowing:

- `get-page-tool` takes a **`slug`** (`/`, `/about`), not a page id. But
  `upsert-section-content-tool`, `delete-section-tool` and the rank tools take a
  **`page_id`**. Get the id from `list-pages-tool` and the section ids from
  `get-page-tool`.
- `get-data-item-tool`, `update-data-item-tool` and `create-meta-for-item-tool`
  take a numeric **`item_id`**, not the slug.
- An item type's field `key` is the metadata key to write; its numeric `id` is
  the `item_type_id` on the item.
- `parent_id` is the numeric id of another data item (from
  `list-data-items-tool`), never its slug.

## Working rules

1. **Orient before writing.** `list-space-tool` first. It returns each space's
   `space_uid`, its `agent_description`, per-type content counts and, when set,
   the front-end URL — enough to tell which space the user means and what
   already exists, without further calls.
2. **Read before you edit.** `get-page-tool` with `mode=draft` (or
   `get-data-item-tool`) to see current values and ids before changing them.
3. **Verify after you write.** A success message confirms the call ran, not that
   the result is what the user wanted. Re-read and check the values landed.
4. **One upsert, all the props.** `upsert-section-content-tool` accepts an array
   of props. Fill a whole section in one call rathe

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: garchi-render-content
description: Write the application code that fetches and renders Garchi CMS content — the server-side Garchi client, page and section renderers, nested sections, data items (blogs/products), item metadata, assets, SEO metadata and draft/preview mode — in Next, Nuxt, Laravel, SvelteKit or any other stack, via the Node SDK, PHP SDK or REST API. Use when implementing or fixing the frontend/server integration for Garchi content. Code only — to create or edit the content itself use garchi-manage-content; to plan a whole project or pick a starter kit use garchi-build-site.
---

# Skill: garchi-render-content

## Scope
- ✅ Build or improve the code needed to **fetch and render** Garchi CMS content (pages, sections, data items).
- ✅ Integrate Garchi CMS into an existing codebase without breaking conventions.
- ❌ Do not manage CMS content (create pages/sections/assets/templates) here — that is `garchi-manage-content`, over MCP.
- ❌ Do not choose or bootstrap a starter kit here — that is `garchi-build-site`.

## Quick start: choose your path
1. **Fresh project → a starter kit is probably right.** Hand back to
   `garchi-build-site`, or read
   [starter-kits.md](../garchi-build-site/references/starter-kits.md). Kits ship
   the SDK, env config, a section renderer and example components.
2. **Existing project, Node or PHP backend → use the SDK** (`@garchicms/garchi-node-sdk` or `garchicms/garchi-sdk-php`).
3. **Existing project, any other backend → use the REST API** via the OpenAPI spec.
4. **Always render from the server** (SSR / server runtime). The API/SDK is **server-side only** and does not support client-side calls.

## Configuration contract
Confirm these exist before writing fetch code (starter kits create them for you):

| Env var | Purpose | Required |
| --- | --- | --- |
| `GARCHI_API_KEY` | Account API key used to authenticate all API/SDK calls. Account-level, not space-level: one key covers every space the account owns | Yes |
| `GARCHI_SPACE_UID` | Target space UID passed to most calls | Yes |
| `GARCHI_API_URL` | API base, `https://garchi.co.uk/api/v2` | Yes |
| `GARCHI_PREVIEW_TOKEN` | Enables draft/preview mode. Per space (Space Settings → Preview Token) | Only if preview is needed |

Nuxt keeps these values in `runtimeConfig` in `nuxt.config.ts` rather than in a
`.env` file. Match whatever the project already uses rather than introducing a
second convention.

**Rule:** the API key is **server-side only**. Never expose it to the client, never
prefix it with `NEXT_PUBLIC_`/`VITE_`/`PUBLIC_`, never commit it, and never call
the Garchi API from the browser.

## Always (non-negotiable rules)
1. **Preserve Visual Editor attributes**
   - For every section component, forward unknown/extra props/attributes to the **root element** (outermost wrapper).
   - Framework-agnostic rule: "Unknown attributes must not be dropped; attach them to the root/host element."
   - Patterns:
     - React/Preact/Solid: spread `...other` on root
     - Vue: `v-bind="$attrs"` on root (if `inheritAttrs: false`, re-bind manually)
     - Svelte: spread `...$$restProps` on root
     - Angular: preserve/pass through host attributes; do not strip unknown attrs
     - Web Components: keep attrs on host or forward to outer wrapper
     - Laravel Blade: ensure attributes are passed to the root element of the section component `{{ $attributes->merge() }}`

2. **Content belongs in Garchi, not in components**
   - Copy, headings, image URLs and list contents come from section props or data-item fields. Do not hard-code them, and do not "temporarily" inline content that the CMS should own.
   - If a value has nowhere to live in the CMS yet, add the prop or template through `garchi-manage-content` rather than baking the value into code.
   - Components own layout, styling and behaviour. They should not encode which page they appear on.

3. **Do not modify reference snippets/docs**
   - Treat [code-snippets](./references/code-snippe

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 4 — file references are metadata, not package contents.