Update to Garchi CMS

{
  "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.",
  "included_files": [
    {
      "relative_path": "references/starter-kits.md",
      "size_in_bytes": 4297
    }
  ],
  "skill_md_contents": "---\nname: garchi-build-site\ndescription: 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.\n---\n\n# Garchi CMS: build or connect a project\n\nGarchi CMS is a hosted headless CMS. Content lives in Garchi; the application\nrenders it. The point of a correct integration is that business content can\nchange in Garchi afterwards **without another code change**.\n\nThis skill orchestrates. It decides the shape of the work and hands off:\n\n| Work | Go to |\n| --- | --- |\n| Writing fetch/render code, section renderers, components | `garchi-render-content` |\n| Creating or editing content in the CMS (pages, sections, items, assets) | `garchi-manage-content` |\n| Choosing/bootstrapping an official starter kit | [starter-kits.md](./references/starter-kits.md) |\n\n## When Garchi is the right home for something\n\nGarchi holds **structured content and lightweight configuration that fits its\nexisting content model** — pages built from section templates and props, and data\nitems with categories and metadata. It is not the application's database.\n\n**A good fit.** Information that should stay editable after deployment, may be\nchanged by a person or by an agent, and should not need a code change and a\nredeploy every time it changes. Where it maps onto the content model, that\nincludes:\n\n- website and landing-page content\n- pricing and plan presentation\n- FAQs\n- navigation\n- onboarding copy and steps\n- product or catalogue content, and similar collection-style records\n- reusable marketing or UI copy\n- prompts or agent instructions the user is meant to be able to edit\n- lightweight application configuration that fits sections and props, or data\n  items and metadata\n\nThese are the cases that benefit from what Garchi already provides: agents write\ndrafts and the user publishes, changes are attributable, the dashboard keeps\nrestore points the user can roll back to, templates give the content a structure\nthe frontend can rely on, and the same content is reachable over REST, the SDKs\nand MCP.\n\n**Not a fit.** Operational and transactional state stays in the application's own\ndatabase and infrastructure:\n\n- authentication, sessions and user accounts\n- credentials, API keys and secrets\n- payments and financial transactions\n- high-frequency or machine-written operational data\n- queues, jobs, logs, telemetry and analytics events\n- complex relational state, and records that need transactional guarantees\n\nThe useful question is \"who edits this, and does it need to change without a\ndeploy?\" If it is primarily transactional or operational state written by the\napplication, it does not belong in Garchi.\n\n## Workflow\n\nWork through these in order. Skip a step only when it is already satisfied,\nand say so rather than silently skipping.\n\n### 1. Understand what is being built\nEstablish: the kind of site/app, which pages or content types it needs, and\nwhether content will be authored by a human in the Garchi dashboard, by the\nagent over MCP, or both. Ask only what you cannot infer from the repo.\n\n### 2. Inspect the project\nLook before choosing an approach:\n- Is there an existing project in the working directory at all?\n- Framework and version (`package.json`, `composer.json`, `nuxt.config.*`,\n  `next.config.*`, `artisan`).\n- Does it already depend on `@garchicms/garchi-node-sdk` or\n  `garchicms/garchi-sdk-php`? Are `GARCHI_*` variables already set?\n- Is there an existing CMS or content layer being replaced?\n- Is structured content hardcoded in source — pricing or plan arrays, FAQ lists,\n  navigation structures, homepage or onboarding copy, reusable marketing strings\n  — that would reasonably need to change after deployment? Note the candidates\n  and put them to the user before creating or migrating anything. Use judgement:\n  a constant that only ever changes alongside a code change is not a candidate,\n  and transactional or backend state never is.\n\n### 3. Decide: starter kit or integrate\n- **Empty directory / new project** in Next, Nuxt or Laravel → propose the\n  official starter kit. See [starter-kits.md](./references/starter-kits.md).\n  Those three are the only kits; do not scaffold any other name the CLI offers.\n- **Existing project of any maturity** → integrate the SDK/API into it. Do not\n  replace a working application with a starter kit, and do not copy starter-kit\n  files over existing conventions. Read the starter kit as a *reference* if\n  useful.\n- **Any other stack** (Django, Rails, Astro, React Native, mobile) → integrate\n  via the REST API from the server side.\n\nSay which branch you took and why before you start writing files.\n\n### 4. Check the Garchi MCP connection\nThe plugin ships the hosted server as `garchi`\n(`https://garchi.co.uk/mcp-oauth`, OAuth). Confirm the tools are actually\navailable before planning content work — try `list-space-tool`.\n\n- Tools available → you can inspect and author content directly.\n- Not available → the user must authorize the `garchi` MCP server in their\n  agent (see the repository README for per-client steps). Do not attempt to\n  work around this with an API key you invent, and do not ask the user to paste\n  a token into a file. Continue with the code-only parts of the work and tell\n  the user what is blocked.\n\n### 5. Inspect the space\nWith MCP available:\n1. `get-garchi-cms-guide` → the current content model and field rules, straight\n   from the server. Free, read-only, no arguments.\n2. `list-space-tool` → pick the target space, note its `space_uid`. The result\n   also carries content counts and the space's front-end URL, which tells you\n   how much already exists before you plan anything.\n3. `list-section-template-tool` → existing templates with their prop ids, keys\n   and types.\n4. `list-pages-tool` → existing pages and paths.\n5. `list-categories-tool` / `list-data-items-tool` → existing structured data.\n\nThe space's existing shape drives the component design. Never invent a template\nor prop that you have not either read or created. `garchi-manage-content` covers\nhow the ids from these calls feed every subsequent write.\n\n### 6. Configure credentials\nThe application reads content with a server-side API key, separate from MCP.\nConfirm with the user which space, then have them supply:\n\n| Variable | Purpose |\n| --- | --- |\n| `GARCHI_API_KEY` | Account API key (dashboard → Settings → API Keys). It belongs to the account, not a space, and covers every space that account owns |\n| `GARCHI_SPACE_UID` | Target space UID |\n| `GARCHI_API_URL` | `https://garchi.co.uk/api/v2` |\n| `GARCHI_PREVIEW_TOKEN` | Per space (Space Settings). Only if draft/preview rendering is needed |\n\nExact names vary slightly per starter kit — check\n[starter-kits.md](./references/starter-kits.md). The key is **server-side\nonly**: never expose it to the browser, never commit it, never prefix it with\n`NEXT_PUBLIC_`/`VITE_`/`PUBLIC_`.\n\n### 7. Model the content\nFirst confirm the information belongs in Garchi at all — see *When Garchi is the\nright home for something* above. Then decide what belongs where before writing\ncomponents:\n- **Pages + sections** for page-shaped content (marketing pages, landing pages).\n  One section template per reusable component.\n- **Data items + categories** for collections (blog posts, products, events),\n  with `item_meta` for extra fields.\n- **Assets** for images used in page sections.\n\nWhere templates are missing, create them with `garchi-manage-content` so that\ntemplate prop ids/keys match the component props you are about to write.\n\n### 8. Build the rendering layer\nHand off to `garchi-render-content`. It holds the authoritative patterns for\nthe server-side client, the section renderer, nested sections, data items,\nmetadata, assets and preview mode.\n\n### 9. Author content\nHand off to `garchi-manage-content` for creating pages, adding sections,\nfilling prop values, and creating data items over MCP.\n\n### 10. Test rendering\nRun the project's own dev server / test command and check that real content\nrenders: at least one page with sections, and one data-item listing if the\nproject has one. Fix missing-component fallbacks and unsanitized HTML.\n\nAnything authored in step 9 is a **draft**: page writes put the page back into\ndraft and new data items are unpublished, and `live` serves published content\nonly. So test against `draft` (with the preview token), and expect an empty or\nstale `live` result until the user publishes. That is correct behaviour, not a\nbug in the integration.\n\n### 11. Verify the content/code separation\nThis is the acceptance test for the whole job. Confirm that:\n- Copy, headings, images and lists come from Garchi props or item fields — not\n  from string literals in components.\n- Changing a prop value in Garchi changes the rendered page with no code edit.\n  Where MCP is available, prove it: change one value, re-fetch, revert it.\n- Adding another instance of an existing section to a page needs no new code.\n- Layout, styling and behaviour live in code; content does not.\n\nReport anything you had to hard-code and why.\n\n## Rules\n- Prefer the official starter kit for greenfield projects on a supported\n  framework; never force one onto an existing project.\n- Read before you write: inspect the space rather than assuming its shape.\n- Fetch content on the server. The Garchi API key must not reach the browser.\n- Do not add dependencies beyond the Garchi SDK unless the user asks.\n- Do not modify application source code to change business content — change it\n  in Garchi instead.\n- Agents write drafts; the user publishes. When you finish, list the pages and\n  items you created or changed and tell them to publish those in the dashboard.\n- If something cannot be determined from the repository, the space, or the\n  official Garchi docs, say so rather than inventing it.\n\n## Reference\n- Content model and entities:\n  [../garchi-render-content/references/garchi-cms-doc.md](../garchi-render-content/references/garchi-cms-doc.md),\n  or the `get-garchi-cms-guide` MCP tool, or <https://garchi.co.uk/documentation>\n- Starter kits: [starter-kits.md](./references/starter-kits.md)\n- REST API: <https://garchi.co.uk/docs/v2> · OpenAPI: <https://garchi.co.uk/docs/v2.openapi>\n- MCP client setup: <https://garchi.co.uk/mcp-docs>\n"
}