Glossary

These words carry the model, and the manual uses each of them in one sense only. Where a page says one of them, it means what is written here.

There are 55 of them. Each is written once in the repository and rendered here, so this page and the tool cannot drift apart.

The shape

Who the participants are. Everything below is stated in these words.

Environment

A named relationship between this project and one site. Declared in cwp.yml under environments:, with a provider, a locator, a URL and a mode.

The name is the identifier everything else hangs off: the ref file, the marker on the site, the guard decision, the run record.

An environment is not a site and not a stage. The same site may be declared twice under two names with two modes. The guard answers differently to each.

local is an environment like any other; see local.

family

One feature of a plugin or theme, with every place it keeps state, declared once and carried as a unit. A family names seven kinds of member: its toggle, its options with a class per path, its post type and meta, the meta it writes on other groups’ posts and terms, the value another artifact has to hold, the steps the target needs after the data lands, and what never travels (S-0024).

A family is data: one YAML file per owner, cwp’s own or the project’s under cwp/families/. features: in cwp.yml switches one on by <owner>/<family>. The config reader expands it into a settings group, a content group, meta rules and the scrub’s lists. No op learns an option name (ADR-032).

The test for a family is whether the feature works on the target with what the tree holds. A settings group carries keys; a family carries a feature. Two incidents made the difference visible: a post type carried without the transient the target had to clear, and SEO fields carried without the flag the builder’s tree had to hold.

cwp asserts a value in another artifact and never writes it. A family and a hand-written group naming the same key or post type are two writers of one name, and the config reader refuses them.

Local

The environment name cwp init writes into cwp.yml for the site on this machine: a DDEV container, reached through the ddev provider.

local is a name, not a direction and not a kind. A step that writes to the local site is not safer by being local; it is subject to the same plan, the same effect declarations and the same guard ladder.

Prose that means “on this machine” says so; prose that means the environment says local and means the entry in cwp.yml.

Not a synonym for “the tree”. The tree is the repository; local is a WordPress install sitting beside it.

Project

A directory with a cwp.yml at its root, holding the tree and the configuration that names the environments.

A project is what a command is standing in. A command that needs one and cannot find one refuses, and the fix hint is cwp init.

The project is one of the two layers of configuration. The other is the machine config, which holds what belongs to this computer rather than to this project.

Site

A WordPress install: a database and a filesystem. The DDEV container on your machine is one; so is dev, so is prod, so is a plain host reached over ssh. None of them has history, and none of them is more or less a site than the others.

The distinction the manual does not draw is “local versus remote”. A site on your machine and a site on the far side of the network differ in distance and in what a guard will let you do to them, never in kind.

Where the subject is the shape rather than the install, the word is spoke.

Spoke

A site, seen from the tree. The word appears where the subject is the shape rather than the install: the tree is the hub, every site is a spoke, and an environment argument names which spoke rather than which direction.

There is no arc from one spoke to another going out. Every upward write passes through the tree. That is a fact about the shape rather than a promise about the code. Direction, and the tree it is measured from names the three edges that skip the hub.

Tree

The committed working copy. Your repository as it stands on disk: the content tree, the design system, the settings files, roles.yml, inventory.yml and the tracked paths.

The tree is the only participant with history, the only one that shows a diff, and the only one a review can happen to. It is also the origin of every direction cwp reports: pull reads into it and push writes out of it.

It is not the site. What the tree describes and what a WordPress install holds are different sets, and cwp coverage is the command that measures the difference.

The relationship between a tree and one environment

What cwp remembers about a pairing, and what the git verbs act on.

Activity

What editors did on an environment since the last transfer. Counted from WordPress revisions and from the item hashes, never from what cwp itself wrote.

Activity is not drift and not the ledger. Drift says the two sides disagree and which one moved. The ledger says what cwp did. Activity says what people did while cwp was not looking. Of the three, only activity says whether a pull is worth running.

cwp measures it against base rather than seen. The question is what is not in the tree, not what has appeared since somebody last checked.

A count of activity is a floor. A revision falls off the cap at 100, a menu or a term produces none at all, and a deletion leaves nothing behind but its absence.

Adopt

Minting the mutual record that says this project manages this environment. cwp adopt <env> writes a marker onto the site, writes a ref into the tree, derives the scope from what the site registers, and reads the tree down for the first time.

Adopting is the one command whose subject is writing identity. Nothing else crosses to an environment that has not been adopted. Both halves matter. A site that carries the record beside a tree that does not means another checkout adopted it. cwp reports that and refuses to resolve it on your behalf.

The same command takes consent for cwp’s own bookkeeping. A later read that leaves a marker is not asking again. The effect that carries it says so on its face.

--release takes it back, ending the relationship and deleting no history. The marker comes off the site. The ref stays in the tree, so the log of what happened remains true.

Base

The state the last transfer agreed on. It moves when cwp carries something, a pull down or a push up, and never merely because cwp looked.

cwp asks “has this environment moved?” against base. If reading moved it, every cwp status would erase the evidence of drift it was run to find.

On a push, base and seen move together: cwp wrote the state, so the environment now looks exactly like what it agreed to.

Canonical form

The one spelling a thing has in the tree, so that two runs that mean the same produce the same bytes.

Six rules govern it: ordering, key ordering, line endings, absent versus empty, how ids are spelled, and what it leaves out entirely. Without them a re-read produces a diff nobody can review.

A field the file no longer carries has to disappear on a write. cwp therefore manages meta by replacement rather than by merge.

Coverage

How much of what a site holds the tree describes. Measured, not assumed.

The tree and the site are different sets. Coverage is the number that says by how much. cwp coverage is the command whose subject is that difference.

Test coverage is a different number. This project reports that one too, and it is a property of the code rather than of a relationship.

Crossing

A run that carries state between the tree and one environment, in either direction: cwp pull and cwp push, and cwp deploy as push plus its post-steps.

The word separates two things a command surface blurs. A crossing carries everything under management and moves the base. A survey carries nothing and moves only seen: cwp status, cwp coverage, cwp content list. Two of cwp’s three refusals are properties of a crossing and fire on no survey.

cwp access is the deliberate non-crossing. It converges one environment to its own declared state. That state is the one value that must not travel.

Drift

A difference between what the tree describes and what a site holds, measured against the base rather than between the two ends directly.

Three-way, always. Two-way tells you something differs. Three-way tells you which side moved. A person can act on the second answer and not on the first.

Ledger

The record of what a run decided and did, written where the next run and the next person can read it: the ref in the tree, and the run record on the site.

The ledger is not the journal. The journal is what a person watching the terminal reads; the ledger outlives the terminal.

A guard ledger is the narrower sense. It holds what the guard ladder answered for one run: whether the environment was protected, whether a restore point was taken, and which exemption applied.

Marker

What cwp leaves on an item to say a transfer happened. _cwp_sync in post, term and menu meta.

The marker is cwp’s own bookkeeping, agreed to once at adopt. It changes nothing anybody wrote. It records that a transfer happened. Without that record cwp cannot compute drift on a term at all.

cwp declares it as an effect and exempts it from the guard ladder by name. Refusing a read of a protected environment over it would protect that environment from something it is not protected from.

Mode

What this project may do to a spoke, set in cwp.yml. One key per environment, defaulting to managed.

• managed — a partner, guarded by a restore point and a confirmation.
• protected — the same partner, with every write out of the tree refused, and exit code 5, until --force is passed. The refusal fires under --dry-run as well.
• source — read-only, and no flag opens it: the refusal comes before the guard ladder rather than being a rung of it.

Mode is a property of the site rather than of the direction. Two environments can sit at the same distance and answer the same write differently. The git analogy stops here first.

An environment has a mode has the trade a source makes, and what a capture from one cannot carry.

Perimeter

Wer durch welche Tür einer site kommt, nach welcher Prüfung. Eine Deklaration je environment unter perimeter:, als Stufe oder als Matrix aus Türen und Werten. Die Erreichbarkeit der Site ist eine der Türen.

Der Perimeter steht oberhalb der drei Seams. Jede

Ref

The committed record of what crossed between this tree and one environment, and when. One file per environment: cwp/refs/<env>.yml.

The ref holds the base and the seen sides of the relationship. It is the authority; the marker on the site is the witness. The witness survives a lost repository and tells a second checkout what happened.

Six places write it. Each declares the write as an effect rather than doing it quietly.

Scope

What “everything under management” means for this project, declared in cwp.yml: which post types, taxonomies, menus, widget areas, roles, settings keys, plugins, themes and locales cwp is responsible for.

cwp derives the scope from the site at adopt, from what WordPress registers rather than from a guess. It then commits it: a declaration, not a live query. An environment that registers something the scope does not name is reported, never adopted quietly:

prod registers 2 post types the scope does not name:
  product     1,284 entries   (WooCommerce)

Widening it is explicit: cwp adopt <env> --rescope proposes the change as a diff and writes nothing without consent.

--only narrows a run to part of the scope; it never widens it.

Seen

The state cwp last observed, as distinct from the state it agreed to.

The upward refusal does not read it. It compares base against what its own survey read from the environment. The comparison is git’s non-fast-forward, asked of a fresh reading rather than of a remembered one. It cannot go stale, and it does not depend on what the operator last typed.

Tracked

A path this project declares as belonging to the tree and travelling with it. Listed under tracked: in cwp.yml.

A tracked path is a repository path by definition, so an upward write of one has a committed source and is reproducible.

Tracked is not the same as committed: a path can be tracked by cwp.yml and uncommitted in git, and a run that writes upward from a dirty tree says so.

Uid

The identity cwp gives an item so it can be recognised across a rename, held in the item’s meta and in the tree.

A slug is not an identity. Renaming a page would otherwise create a second one and orphan the first. The uid recognises the rename.

An item with no uid is not under management. A read that gives one is an adopt, and it writes to the site.

What a run is made of

The vocabulary of a single command, from the plan it builds to the steps it takes.

Direction

Which way a change moves relative to the tree. Down is into the tree, up is out of it.

Discovered, not declared. The same command is up on Tuesday and local on Wednesday, decided by a positional argument. Direction sits on the effect and never on the command. A first draft put direction: "up" | "down" on the command, and that is a false guarantee.

Principle P1 is the asymmetry: database and uploads flow downward by default.

Dry run

A run that builds the real plan and stops before apply. --dry-run.

survey reads and writes nothing, so a dry run reports the real conflicts, the real dangling references and the real uploads rather than a hopeful summary.

The guards still run. cwp refuses a dry run against a protected environment. Merge refusal into consent and cwp push prod --dry-run starts printing a plan for a write it would never permit.

Effect

One entry in a plan: one thing the run will do. It says where it writes, what it can be reproduced from, whether a failure stops the run, and whether it destroys anything.

Direction is discovered, not declared. The same step is a remote write with an environment argument and a local one without. writes therefore sits on the effect and never on the command.

Two named exemptions live on an effect rather than in a guard: unreproducible for the source rule, owned for cwp’s own marker. Each is written on the effect, so neither is a hole.

Guard ladder

The ordered set of refusals every upward write passes. A source environment is refused before the ladder; a protected one is refused on it without --force; an unsourced upward write is refused on it always; a restore point is taken before anything lands.

The ladder reads the plan’s effects and never asks what the command is called. A run that declares no remote write is never asked. An undeclared write is a write outside the ladder.

mode: source is not a stronger rung, it is not a rung. No flag opens it.

Operation

One pipeline with one subject: read the content down, converge the roles, mint an application password. Written as survey, refuse, apply, assert.

Called an op in the code.

A command is not always one operation. cwp pull runs six and is one run: one plan, one refusal, one restore point, one confirmation.

An operation that runs other operations’ phases is a composite. It carries their effects into its own plan. A composite that declares nothing for a sub-plan that writes is the shape of B-080.

Phase

One of the named stages every operation passes through, in one order. survey, refuse, consent, restore point, tree snapshot, apply, the self-checks, assert, record, commit, report.

The order is the safety model. Refuse comes before consent and runs under --dry-run, so a dry run against a protected environment is still refused. The restore point sits after consent and before the write. Commit comes after the post-conditions held.

survey reads and writes nothing, so a dry run prints something true rather than a guess.

Plan

What a command builds before it touches anything, and what the guards read. A list of effects, the environment, and the notes that go with them.

The plan is not a preview and not a summary. It is the contract. The guard ladder reads it, --dry-run prints it, and cwp checks the run against it.

A write nobody declared is a write outside the ladder. The plan is not decoration. It has to be true.

Restore point

A backup of the far side, taken before an upward write lands. A provider backup where the host has one.

Its position carries it. It comes after consent, so a run you declined backs nothing up. It comes before the first overwrite, so there is a way back.

cwp takes one unless you waive it. The run reports the waiver rather than assuming it.

Self-check

A comparison the run makes about itself at the end of every command. Two of them: whether the run wrote something the plan did not describe, and whether it skipped a step the plan declared.

Both print a warning and ask for a report. Neither stops the run: the work is right and cwp’s account of the work is wrong.

In the test suite they throw. CWP_STRICT_PLAN=1 turns each warning into a failure, so the existing tests enforce the rule with no new test cases.

Step

One effect as the run performs it. The label on the effect is what joins the two: the plan names the step, and the run takes it under that name.

Each step runs under its own declaration. best effort then decides, per step, how a failure ends. The run reports a step it announced and never took.

A step performed with no effect declaring it is an error, not a warning.

Tree snapshot

The commit the tree stood at before the run wrote to it, recorded so a local change can be undone.

The counterpart to the restore point on the other side: one protects the site, one protects the repository. A run that writes files reports the revision to check out to get back.

The rules a run obeys

Properties a step declares about itself, and the machinery that reads them.

Best effort

A property of one effect: whether a failure there stops the run. bestEffort: true means the run reports the failure and carries on.

No default, ever. Every effect states it. A default would decide for somebody that a failed step was survivable.

A run that continued past a best-effort failure still ends non-zero. Carrying on finishes the work that can be finished. It does not call the run clean.

Capability

Something a provider or builder can or cannot do, probed at run time rather than hardcoded.

Where nobody can verify something, cwp puts it behind a capability check that degrades to a clear instruction rather than to a silent skip. A missing capability produces a refusal with a fix hint, never a quietly narrower run.

The probe stays even where the answer is known. It is cheap and cached. cwp does not hardcode a behaviour nobody can see.

Committed source

The path in the tree an upward write originates in. Principle P2: every upward write has one.

A committed source makes a write reproducible: the same repository state produces the same write. The guard ladder refuses an upward effect with no source. The one exemption, unreproducible, carries its reason on the effect, and the run reports it.

Destructive

A property of one effect: whether it can discard something that was there.

cwp names a destructive step in the confirmation prompt rather than counting it. Somebody agreeing to a run has to see which part of it cannot be undone.

It is often a property of the run rather than of the step. An update that overwrites an edit made on the site is destructive. The same update against an untouched post is not.

Finding

One machine-readable statement about what a run found, with a code, a severity, a message and a fix hint.

One vocabulary, two types: a run reports a finding and throws an error. Both carry the same code. A reader of the JSON and a reader of the terminal see the same thing under the same name.

Fix hint

The sentence that says what to do about a failure, carried by every user-facing error.

Not optional. “Cloudron CLI not found” is not acceptable output. “Cloudron CLI not found — install it with npm i -g cloudron” is.

A hint names a command or a file. A hint that says “check your configuration” is the failure this rule exists against.

Invariant

A safety rule this project holds structurally, named in src/domain/policy/invariants.ts with the test that enforces it.

An invariant is not a convention. Each entry points at its test. A structural test fails the build if that test is renamed or deleted. The catalogue cannot quietly become a list of things that used to be true.

Output contract

Human output to stderr, machine output to stdout. Never mixed.

The split sends a run’s stdout into jq while a person watches the same run on stderr. A journal line on stdout would corrupt the envelope; a JSON envelope on stderr would be invisible to the pipe.

The envelope carries the command id, the steps, the warnings, the error and the data: the same findings the terminal showed.

The parts of a site cwp manages

What travels, and the two interfaces everything host-specific and builder-specific sits behind.

Ability

A callable operation a site registers and exposes to a caller. It may be Bricks’, the child theme’s, WordPress core’s or the MCP adapter’s.

Two surfaces, and they are not the same: what Bricks registers, and what a call reaches on a real site. Both are correct and neither replaces the other. cwp keeps the two apart.

The counts are data. They belong to a Bricks version and move with it.

Artifact

Eine Datei im Baum, die hält, was eine Seite hält. cwp pull liest sie von einer site oder vom edge, cwp status vergleicht sie gegen den ref, cwp push schreibt sie zurück. Ein Mensch ändert sie im Editor und committet; er schreibt sie nicht von Hand.

Das Gegenstück zur declaration. Die Deklaration in cwp.yml sagt, was cwp verwaltet; das Artefakt sagt, was die Seite dazu gerade hält. Beide gehören in den Baum, und die Richtung unterscheidet sie: eine Deklaration liest cwp, ein Artefakt schreibt cwp.

Ein Artefakt heißt nach dem, was es hält. Nach der Gruppe, wo dieselbe Sache auf jeder Umgebung dieselbe ist (settings/core.yml). Nach der environment, wo jede Umgebung eine andere Seite hat (edge/dev.yml, cwp/refs/dev.yml): der Rand vor dev ist eine andere

Builder

The seam that answers “what does this page builder store, and how”. Bricks is one implementation; none is another.

A builder reads and writes a page’s payload, knows its own transfer format, and answers what it can regenerate after an import. Everything generic is above the seam and shared: media paths, internal links, canonical ordering.

A page builder is not the subject of any command. A command’s subject is the content; the builder is how that content is stored.

Declaration

Was ein Mensch in cwp.yml schreibt, damit cwp weiß, was es verwaltet und wie. In cwps Vokabular, von Hand, gelesen und nie von cwp geschrieben, bis auf cwp init und cwp config set.

Das Gegenstück zum artifact. settings.core: {preset: …} ist Deklaration, settings/core.yml ist Artefakt. environments.dev.edge deklariert, dass vor dev ein Rand steht; edge/dev.yml hält, was die

Design system

The site-wide things a page builder holds that are not one page: colour palettes, typography, global classes, templates, theme styles.

It is site-wide, so it travels as its own part of the scope. A run that carries one page must not carry the palette with it by accident. A run that carries the palette changes every page at once.

Edge

Der Dienst zwischen Besucher und Origin, der weder die site noch der Host ist. Reverse-Proxy, CDN, Web Application Firewall, meist mit der DNS-

Die dritte seam. Ein Unterschied je Anbieter des Rands gehört hinter Edge, nicht in eine Operation und nicht in einen provider.

Ein Cache auf dem Host ist kein Edge: der

Inventory

The declared set of plugins, themes, languages and core version for an environment, held in inventory.yml.

The file is desired state. A run computes the actions that bring an environment to it: install, activate, deactivate, version, remove. Each action is one effect with its own line in the confirmation.

Removing is destructive and says so. Everything else is best effort.

Mail guard

A must-use plugin that intercepts outgoing mail on a copy of a production database.

Every pull that imports a database installs it, whether or not scrubbing is on. The rule names the reason rather than a command: a fourth command that brings a database down inherits it by being what it is.

assert checks it as a post-condition, so every path that got there is covered.

Provenance

The record a run leaves on the environment it wrote to: an option and a dashboard widget saying what was pushed, from which revision, and when.

provenance: false switches it off. The effect then disappears from the plan rather than the step silently doing nothing.

Never fatal. The pages are on the target. A note about them that failed to write is worth a line and not an exit code.

Provider

The seam that answers “how do I reach this host”. One implementation per kind of host: Cloudron, ssh, DDEV.

A provider builds the command that reaches a site, declares its capabilities, and says whether a call writes to the far side. It never decides what to write. The operation decides that.

Where a provider cannot do something, it refuses with an instruction rather than skipping quietly.

Scrub

Making a copy of production data safe to work on: anonymised users, truncated log tables, deleted transients, and the site marked not indexable.

Local only. cwp scrub acts on the site on this machine, and every one of its six steps declares writes: "local".

Scrubbing is not what installs the mail guard. The guard goes in whenever a pull imports a database, scrubbing on or off. The database is the reason, not the scrub.

Seam

An interface with more than one implementation, where a difference this project must not decide for itself is answered. There are two: provider and builder.

The test for a seam is the question it answers. A difference per host belongs behind Provider. A difference per page builder belongs behind Builder. An if (provider === "cloudron") outside tools/providers/ is the defect the seam removes, and a structural test fails the build on it.

Where the answer is “it goes above both seams”, write the claim down. Every seam leak this project has had arrived as a caller deciding something the seam should have answered.

stage

Wo eine environment in ihrem Leben steht: build, launch, live oder handover. Deklariert je Umgebung unter stage:; local ist immer build. Die Stufe sagt, ob ein Befund warn oder fail ist, welche Guards ein Push zusätzlich nimmt, und was cwp status zeigt (ADR-034).

Die guard ladder fragt, ob ein Schreibzugriff erlaubt ist. Die Stufe fragt, ob das