Total CMS

View saved version →

---
name: totalcms
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.
---

# Building a Total CMS (T3) site

This project **is a website** built on Total CMS, a flat-file PHP CMS. There is
**no database** — all content is JSON under `tcms-data/`. Configure via
`config/tcms.php` (deep-merged — specify only keys you change).

## Is this copy current?

This skill is a copy of the one shipped with the installed CMS, so it can fall
behind. At the start of a session run `vendor/bin/tcms skill:install --check`.
If it reports stale, run `vendor/bin/tcms skill:install` and then tell the user
to start a new session — the text already loaded cannot replace itself. The
stamp is a hash of the skill's own content, not the release number, so only real
changes to the skill flag it.

## Where things are

T3 ships in two layouts. Check which one you are in before running anything.

- **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 -->
- **Zip install** — the CMS *is* the folder you are in (conventionally `tcms/`).
  CLI `php resources/bin/tcms`, run from that folder; docs `resources/docs/`;
  config `config/tcms.php` inside it; content in `../tcms-data/` beside it. An
  update replaces the folder's `config/ public/ resources/ src/ vendor/`
  wholesale, so **never add files inside them**.

If this skill was installed by `skill:install` on a zip install, the paths
throughout it are already rewritten for that layout.

Most commands accept `--json` for machine-readable output — prefer it when
scripting. Run `vendor/bin/tcms list` to see everything.

## Write through the CLI, never to the files

`tcms-data/` is a store, not an editing surface. It is tempting to create or
edit the JSON files in it directly — it usually appears to work, which is what
makes it dangerous. **Always go through the CLI (or the API/MCP), which is what
the admin does:**

| To… | Run |
|---|---|
| create an object | `vendor/bin/tcms object:create <collection> -` (JSON on stdin) |
| change part of an object | `vendor/bin/tcms object:patch <collection> <id> -` |
| load many objects | `vendor/bin/tcms collection:import <collection> file.json` |
| add or change a schema | `vendor/bin/tcms schema:import schema.json`, then `schema:lint <id> --strict` |
| create a collection | `vendor/bin/tcms collection:create …` |
| seed structure + content together | `vendor/bin/tcms jumpstart:import file.json` |

A save through the CLI validates the object against its schema, fills in what
the schema derives (default types, autogen ids, `created`/`updated`
timestamps, image and video metadata), updates the collection's `.index.json`
and counts, and fires the events the rest of the system listens for (search
indexing, automations, MCP change notifications). A file written by hand gets
none of that: one bad comma takes the whole collection offline, an unindexed
object is invisible to the admin tables, sitemaps and queries until
`repair:index` runs, and timestamps and derived fields are simply missing.

Reading the files is fine (`cat`, `jq`), though `object:get --json` is the
same data validated. If you ever *must* touch a file — recovering data, say —
validate the JSON, then run `vendor/bin/tcms repair:index <collection>` and,
for a schema, `schema:lint <id> --strict`.

This applies to **content and structure**. Templates under `builder/` and the
config file `config/tcms.php` are files by design — edit those directly.

## Where to look things up

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

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