Eightyfour

Starting a new WormPress site

A WormPress site is a small repository of its own. The engine is not in it: the site depends on the published engine packages by version, and the repository holds only what makes this site itself. This is how a new one starts, in the order that works.

1. Make the repository

Create an empty repository on the forge under the site's own organisation, for example anybean/wormpress, and clone it into projects/<org>/wormpress in your checkout.

2. Add the bundle files

Five files make a site. Everything else is optional.

  • package.json. Depends on @eightyfour/wormpress and @eightyfour/wormpress-web at the current published versions, with the scripts dev, api, web and import mapped to the wormpress command, and a wormpress block declaring this site's local ports. Every site gets its own pair so they run in parallel. Take the next free pair (huff 3411/3210, Moss Lane Farm 3421/3220, lifetime 3431/3230, eightyfour 3441/3240, anybean 3461/3260).
  • .npmrc. One line routing the @eightyfour scope to the forge registry: @eightyfour:registry=https://forge.huffbreathwork.app/api/packages/eightyfour/npm/. The token lives in your own ~/.npmrc, never in the repository.
  • site.json. The site's name (this becomes its database name and module slot, so keep it a simple slug), the author, and the settings the engine seeds on first boot: site name and tagline, the four colours, the primary navigation, footer text, default SEO title and description, posts per page and the front page path.
  • theme/global.css. The fallback palette as --wp-bg, --wp-text, --wp-primary and --wp-accent. The engine injects the live values from Settings on top.
  • content/. Seed pages as content/pages/<slug>.mdx with front matter (title, slug, path, status, showInNav) and seed posts as content/posts/<slug>.mdx (title, slug, excerpt, date, status, categories). One front page and one post are enough. These only seed an empty database; once the site is live the admin owns the content and redeploys never touch it.

Leave templates/ empty to start. The engine ships a complete default theme, and any file you later add under templates/ replaces the engine's file of the same name (layout.tsx, home.tsx, page.tsx, post.tsx, blocks/index.tsx and so on), so a site can take its theme over one file at a time. Static media goes under public/wp-content/ and is served at /wp-content/. Site-specific server code, if it ever needs any, lives under modules/api/ with its own routes, controllers and migrations.

3. Register it locally

  • Add the site directory to the workspaces list in projects/package.json and run npm install there. The workspace links your local engine checkout into the site's node_modules, so engine edits are live in every site at once. If you ever see the site pull a real copy of the engine from the registry instead, its version pins have fallen behind the checkout: bump them and remove the stale copy.
  • Give the dev overseer a project entry for it (name, tmux window, site directory, the ace-site mapping and the site-control entry), so ./dev up <site> and the overseer's web page know it.
  • Add its port pair to the ./wp site table for the record.

4. Boot it

./dev up <site>, or npm run dev in the site directory. The runner starts the shared dev Postgres, creates the site's database, runs every migration, seeds the bundle because the database is empty, and serves the api and the site with its admin on the ports you declared. Sign in through the overseer's admin button, which mints a dev token, or with npx wormpress ace admin:token.

Commit and push the bundle. Nothing deploys from that push until a studio service exists for the site.

5. Take it to production

In the studio, create the app and a service pointing at the site's repository, with the registry-model manifest so the image installs the engine at the site's pinned version. Attach its addons (Postgres, object storage for uploads, realtime), set the domain, and let the first deploy seed it. From then on the site's content is owned by its admin, engine upgrades are a version bump in the site's package.json, and template changes deploy on push.