Update to Total CMS

{
  "description": "Use when building, editing, or managing a Total CMS (T3) site — Site Builder pages and SEO, collections, schemas and field choice, objects and imports, forms and public registration, access groups, automations, Data Views, search, feeds, the MCP server, the tcms CLI, the frontend/Vite pipeline, push/pull to production, or writing a T3 extension. Covers the local build workflow end to end.",
  "included_files": [
    {
      "relative_path": "references/cli.md",
      "size_in_bytes": 5498
    },
    {
      "relative_path": "references/data-model.md",
      "size_in_bytes": 11112
    },
    {
      "relative_path": "references/extensions.md",
      "size_in_bytes": 4615
    },
    {
      "relative_path": "references/features.md",
      "size_in_bytes": 10694
    },
    {
      "relative_path": "references/frontend.md",
      "size_in_bytes": 1383
    },
    {
      "relative_path": "references/going-live.md",
      "size_in_bytes": 3165
    },
    {
      "relative_path": "references/mcp-content.md",
      "size_in_bytes": 3236
    },
    {
      "relative_path": "references/site-builder.md",
      "size_in_bytes": 5545
    }
  ],
  "name": "totalcms",
  "skill_md_contents": "---\nname: totalcms\ndescription: Use when building, editing, or managing a Total CMS (T3) site — Site Builder pages and SEO, collections, schemas and field choice, objects and imports, forms and public registration, access groups, automations, Data Views, search, feeds, the MCP server, the tcms CLI, the frontend/Vite pipeline, push/pull to production, or writing a T3 extension. Covers the local build workflow end to end.\n---\n\n# Building a Total CMS (T3) site\n\nThis project **is a website** built on Total CMS, a flat-file PHP CMS. There is\n**no database** — all content is JSON under `tcms-data/`. Configure via\n`config/tcms.php` (deep-merged — specify only keys you change).\n\n## Is this copy current?\n\nThis skill is a copy of the one shipped with the installed CMS, so it can fall\nbehind. At the start of a session run `vendor/bin/tcms skill:install --check`.\nIf it reports stale, run `vendor/bin/tcms skill:install` and then tell the user\nto start a new session — the text already loaded cannot replace itself. The\nstamp is a hash of the skill's own content, not the release number, so only real\nchanges to the skill flag it.\n\n## Where things are\n\nT3 ships in two layouts. Check which one you are in before running anything.\n\n- **Composer install** — the default the rest of this skill assumes. CLI `vendor/bin/tcms`; CMS code and docs under `vendor/totalcms/cms/`; config `config/tcms.php` at the project root. **Never edit `vendor/`** — an update replaces it. <!-- composer-paths -->\n- **Zip install** — the CMS *is* the folder you are in (conventionally `tcms/`).\n  CLI `php resources/bin/tcms`, run from that folder; docs `resources/docs/`;\n  config `config/tcms.php` inside it; content in `../tcms-data/` beside it. An\n  update replaces the folder's `config/ public/ resources/ src/ vendor/`\n  wholesale, so **never add files inside them**.\n\nIf this skill was installed by `skill:install` on a zip install, the paths\nthroughout it are already rewritten for that layout.\n\nMost commands accept `--json` for machine-readable output — prefer it when\nscripting. Run `vendor/bin/tcms list` to see everything.\n\n## Write through the CLI, never to the files\n\n`tcms-data/` is a store, not an editing surface. It is tempting to create or\nedit the JSON files in it directly — it usually appears to work, which is what\nmakes it dangerous. **Always go through the CLI (or the API/MCP), which is what\nthe admin does:**\n\n| To… | Run |\n|---|---|\n| create an object | `vendor/bin/tcms object:create <collection> -` (JSON on stdin) |\n| change part of an object | `vendor/bin/tcms object:patch <collection> <id> -` |\n| load many objects | `vendor/bin/tcms collection:import <collection> file.json` |\n| add or change a schema | `vendor/bin/tcms schema:import schema.json`, then `schema:lint <id> --strict` |\n| create a collection | `vendor/bin/tcms collection:create …` |\n| seed structure + content together | `vendor/bin/tcms jumpstart:import file.json` |\n\nA save through the CLI validates the object against its schema, fills in what\nthe schema derives (default types, autogen ids, `created`/`updated`\ntimestamps, image and video metadata), updates the collection's `.index.json`\nand counts, and fires the events the rest of the system listens for (search\nindexing, automations, MCP change notifications). A file written by hand gets\nnone of that: one bad comma takes the whole collection offline, an unindexed\nobject is invisible to the admin tables, sitemaps and queries until\n`repair:index` runs, and timestamps and derived fields are simply missing.\n\nReading the files is fine (`cat`, `jq`), though `object:get --json` is the\nsame data validated. If you ever *must* touch a file — recovering data, say —\nvalidate the JSON, then run `vendor/bin/tcms repair:index <collection>` and,\nfor a schema, `schema:lint <id> --strict`.\n\nThis applies to **content and structure**. Templates under `builder/` and the\nconfig file `config/tcms.php` are files by design — edit those directly.\n\n## Where to look things up\n\nYou do **not** need to memorize field options or Twig signatures — they ship on disk:\n\n- **On-disk docs (always present):** `vendor/totalcms/cms/resources/docs/<section>/`\n  (`menu.php` is the table of contents, `search-index.json` a prebuilt index).\n  Sections: `get-started/`, `collections/`, `schemas/`, `fields/`, `site-builder/`,\n  `twig/`, `forms/`, `automations/`, `admin/`, `notifications/`, `auth/`, `apis/`,\n  `mcp/`, `extensions/`, `operations/`. `references/features.md` maps every feature\n  to its page. Grep or read these for the long tail.\n- **MCP docs server (fastest lookup):** when the official docs connector\n  (`https://totalcms.co/mcp`) is connected — it ships alongside this skill in\n  the Total CMS plugin — use `docs_search` to find pages, `docs_get` to read\n  one, and `docs_lookup(kind, name)` for exact reference entries (Twig\n  functions/filters, field types, API endpoints, schema config, CLI commands,\n  extension/builder API).\n  The on-disk docs remain authoritative and work with no connection.\n\nPrefer looking things up over guessing; training data is often stale on exact signatures.\n\n## The build loop: add a page to the site\n\n1. **See what already routes:** `vendor/bin/tcms builder:routes` lists every page\n   the router serves and flags conflicts. `vendor/bin/tcms builder:routes --json` to script.\n2. **If Site Builder isn't set up yet,** scaffold a starter:\n   `vendor/bin/tcms builder:init <starter>` where `<starter>` is `business`, `blog`,\n   `portfolio`, or `minimal`. Add `--frontend` to also install the Vite pipeline.\n   This copies templates, ensures the `builder-pages` collection, and seeds demo pages.\n3. **Edit templates** on the filesystem under\n   `builder/{layouts,pages,partials,macros}/*.twig` when a project-root `builder/`\n   directory exists (git-managed mode: it wins over `tcms-data/`, and the admin's\n   template editor is read-only), otherwise `tcms-data/builder/`. Twig global is `cms`;\n   builder helpers are `cms.builder.nav()`, `cms.builder.url(id, params)`,\n   `cms.builder.css/js/asset()`. The layout's `<head>` carries\n   `{% block seo %}{{ cms.seo.head(page|default(null)) }}{% endblock %}` — it emits\n   title, description, canonical, Open Graph and JSON-LD, so a layout must not also\n   hand-write `<title>` or `<meta name=\"description\">`. See `references/site-builder.md`.\n4. **Add a page record.** A page is an object in the `builder-pages` collection.\n   Create it one of these ways:\n   - `echo '{\"id\":\"about\",\"title\":\"About\",\"route\":\"/about\",\"template\":\"pages/page.twig\"}' | vendor/bin/tcms object:create builder-pages -` (one object, file or stdin), or\n   - the **admin UI** (Site Builder → Pages), or\n   - `vendor/bin/tcms collection:import builder-pages <file.json>` for arrays (see `references/cli.md`), or\n   - `vendor/bin/tcms jumpstart:import <file>` for bulk seeding.\n   Key `builder-pages` fields: `route`, `template`, `title`, `draft`, `data` (free-form\n   JSON exposed as `page.data.*`). Full list in `references/site-builder.md`.\n5. **Preview:** `php -S localhost:8080 -t public public/index.php` and visit the\n   page's `route`. Pass `public/index.php` as the router script — without it the\n   built-in server only serves files that exist on disk and never reaches the page\n   router, so every builder page 404s. Clear caches after template changes if\n   needed: `vendor/bin/tcms cache:clear`. Restart the server after adding page\n   records — the route index is cached in the server process.\n\n## Writing schemas and content by hand\n\n**Before writing any schema, read the reference schema** —\n`vendor/bin/tcms schema:get totalcms --json` — and copy property definitions from it.\nIt demonstrates every field type with the settings and help text that go with it.\nPick fields by the shape of the value (`date`, `toggle`, `select`, `number`, `image`…);\n`text` is the last resort. Write every `help` and `description` as a brief to a\nwriter who cannot see the site — agents read them through MCP. Rules, the\nfive meanings of \"category\", and the SEO card: `references/data-model.md`.\n\nThe admin enforces these for you. They only bite when you author JSON that the\nCLI then imports — JumpStart files, `collection:import` payloads, API bodies —\nwhich is exactly what an agent tends to write. (Authoring JSON *for the CLI to\nimport* is fine; writing it straight into `tcms-data/` is not — see \"Write\nthrough the CLI, never to the files\" above.)\n\n- **Every schema must define an `id` property**, not just list `id` in `required`.\n  A schema missing it fails with `The required properties (id) are missing`, which\n  points at your data when the bug is in the schema.\n- **Decks are dictionaries of named items, not arrays.** Each key names one item and\n  must equal that item's `id`:\n  `{\"rows\": {\"first_row\": {\"id\": \"first_row\", ...}}}`\n- **Deck item keys allow only letters, numbers, and underscores** — no hyphens, so\n  Twig can read them as `deck.first_row`. `first-row` is rejected on import.\n- **`field: \"deckTable\"`** stores exactly like a deck but edits as a table.\n\nSee `vendor/totalcms/cms/resources/docs/fields/deck.md` for the full shape.\n\n**Schema work is done when `vendor/bin/tcms schema:lint <id> --strict` is clean** —\nzero errors, zero warnings. Imports validate on the way in, but in-place edits are\nnever re-checked, and the linter flags every property missing the help text AI\nagents rely on. Fill descriptions in on the first pass, not as a follow-up.\n\n## Working against a live site\n\nTwo rules prevent the two worst mistakes:\n\n- **Patch, don't replace.** When editing a live site through its MCP server,\n  prefer `patch_object` (merges only the fields you send). `update_object` is a\n  FULL replace — if you must use it, fetch the complete record with\n  `get_object` + `format: \"html\"` first, edit, strip the decorated `url` key,\n  and write the whole body back. Details: `references/mcp-content.md`.\n- **After launch, the server owns content.** Local seed files go stale by\n  design — never re-import them over live data. Use `pull`/`push` (dry-run\n  first; filters are exclusive). Details: `references/going-live.md`.\n\n## Reference files (read on demand)\n\n| When you are… | Read |\n|---|---|\n| running any `tcms` command / scripting with `--json` | `references/cli.md` |\n| editing builder templates, routes, or page records | `references/site-builder.md` |\n| setting up or building frontend assets | `references/frontend.md` |\n| modeling data — collections, schemas, field choice, descriptions | `references/data-model.md` |\n| wondering whether T3 already does something (SEO, forms, automations, search, feeds, auth…) | `references/features.md` |\n| writing or reviewing an extension | `references/extensions.md` |\n| reading/writing content via the site's MCP server | `references/mcp-content.md` |\n| launching, syncing with production (`push`/`pull`) | `references/going-live.md` |\n| needing an exact field option / Twig signature | `vendor/totalcms/cms/resources/docs/<section>/` (or MCP) |\n"
}