Onboarding an existing site

The quickstart gets a local copy running. A site that has been live for a while needs three more things before you start working in it.

Adopt the environment

cwp adopt prod

Nothing crosses between the tree and an environment cwp has not adopted. On a site that already exists this is the step that does the most work:

• it mints the mutual record, a marker on the site and a ref in the tree, so both sides agree which project manages this environment;
• it derives the scope from what the site registers, rather than from a guess: the post types, taxonomies, menus, widget areas, roles, settings keys, plugins, themes and locales that exist there;
• it reads the tree down for the first time, so your repository starts from what the site holds rather than from empty.

A site that carries an adoption record this checkout knows nothing about means somebody else adopted it. cwp reports that and resolves nothing. Adopting again would mint a second identity over the first.

An environment you are taking content from and will never write to belongs in cwp.yml as mode: source instead. Adoption does not apply to one. Read the trade it makes before you rely on it.

Take a baseline snapshot immediately

cwp db snapshot baseline

Restoring costs five seconds; re-pulling costs minutes. Make it a reflex before any experiment that touches the database. cwp db exists for that.

When the site goes live, say so

cwp launch prod

The launch list runs against the environment, every line names its fix, and when none fails the environment’s stage becomes live. From then on a push there holds on the sandbox captcha key, the mail guard and the scrub’s placeholder accounts instead of warning afterwards, and an agent gets no write there through cwp serve.

Then audit where the site’s own code lives

On a Bricks site with an auto-updating child theme, custom code accumulates in two places it should never be:

• the child theme directory, and
• the theme’s own code-snippet manager.

Both are a problem for the same reason: the child theme auto-updates and will overwrite them. Anything of yours that lives there is one update away from being gone.

The fix is the site plugin that cwp init scaffolds. Move custom code into it and register custom Bricks elements from there on the init hook. The rule to hold, without exception:

No project code in wp-content/themes/. Ever.

cwp does not audit this for you and does not migrate anything. It has no way to tell your snippet from the theme author’s, and a migration that guessed wrong would move somebody else’s code into your plugin and call it done. Read the theme directory and the snippet manager yourself, plan the move, and snapshot before you make it.