Docs and tenant-site publishing

Docs and tenant-site publishing

Clawdie currently uses one Astro/Starlight project inside the Web Service (cms jail) for two related jobs:

• publishing the main docs site
• building tenant-site artifacts one site at a time

This page describes the current supported operator workflow.

Current model

The current deploy shape is:

• Host repo source: /home/<agent>/clawdie-ai/
• Astro project in repo: bootstrap/cms/clawdie-site/
• Astro project in cms jail: /usr/home/<tenant>/<tenant>-site/
• Mounted host source in cms jail: /usr/home/<tenant>/<tenant>-site-host/
• Docs webroot in cms jail: /usr/local/www/<tenant>/
• Tenant-site output root in cms jail: /usr/local/www/<tenant>/sites/

The cms jail keeps its own node_modules/ and build output, but reads source from the host repo via nullfs mount.

Docs publishing

Source of truth

For docs content, the source of truth is:

• docs/public/
• docs/public/sl/

The Astro tree under bootstrap/cms/clawdie-site/src/content/docs/ is a generated consumer, not the editorial source of truth.

Day-to-day docs workflow

1. Edit docs in docs/public/ on the host.
2. Pull or update the host repo if needed:

git pull

3. Build and deploy from inside the cms jail project:

cd /usr/home/<tenant>/<tenant>-site
npm run deploy

That deploy flow runs:

1. scripts/sync-host-config.mjs
2. scripts/sync-public-docs.mjs
3. astro build
4. deploy into the cms jail webroot

npm run deploy protects /usr/local/www/<tenant>/sites/ by default, so a docs deploy does not wipe tenant-site output.

Strapi editorial flow

When docs-related content changes in Strapi:

cd /usr/home/<tenant>/<tenant>-site
npm run export-strapi

Then:

1. review the exported snapshot on the host with git diff
2. commit the changed snapshot
3. deploy again with npm run deploy

This keeps Strapi as an editorial input, not the only source of truth.

Tenant-site publishing

Tenant-site publishing is currently manual by design.

Run this command from the host repo root, not from inside the cms jail Astro project.

Supported command:

npm run publish-tenant-site -- --tenant <tenant> --site <site>

Example:

npm run publish-tenant-site -- --tenant mevy --site blog

What the command does

It currently:

1. validates the tenant and site in infra/tenants.yaml
2. rejects disabled sites
3. prepares a site-specific content pack from:
   • a committed Strapi snapshot when present, or
   • generated registry content as fallback
4. builds the Astro project inside the cms jail
5. syncs the built output into:
   • /usr/local/www/<tenant>/sites/<tenant>/<site>/

Current operator flow

1. Declare or update the site in infra/tenants.yaml
2. If Strapi content changed, run:

cd /usr/home/<tenant>/<tenant>-site
npm run export-strapi

3. Review and commit the snapshot diff on the host
4. From the host repo root, publish the site:

npm run publish-tenant-site -- --tenant <tenant> --site <site>

5. Verify:
   • tenant home shows the site as available
   • the site host serves real content

Publish state meanings

Tenant-site publishing now has a few explicit states that show up in reports and verification output:

• planned_only The site is declared in the registry, but no served output exists yet. This is normal before the first manual publish.
• partial Some enabled sites have published output and some are still only declared. This is also acceptable in the current manual V1 workflow.
• available Every enabled site currently has served output where the platform expects it.
• inconsistent The live output and the publish manifest disagree. This is the state to treat as broken.

What verify checks now

just setup -- --step verify now checks tenant-site publishing more directly than before. It does not only ask whether the shared Astro build exists.

For tenant sites it checks:

• whether a served index.html exists in the expected site webroot
• whether a publish manifest exists for served output
• whether the manifest still matches the declared tenant, site, host, and target paths

This means:

• planned_only, partial, and available do not fail verify by themselves
• inconsistent does fail verify, because it means runtime truth and publish bookkeeping drifted apart

Current limitations

Be explicit about what is not true yet:

• tenant-site publishing is not automatic
• it is not webhook-driven
• it is not a full per-site Astro app model yet
• docs publishing and tenant-site publishing still share one Astro/Starlight project

That shared-project design is acceptable for the current phase because it keeps the publish path inspectable and reversible.

Required local jail environment

Keep tokens and secrets in the cms jail .env, not in git.

Common values:

• STRAPI_BASE_URL
• STRAPI_API_TOKEN
• CMS_WEBROOT
• CMS_DEPLOY_PROTECT

Legacy note

Older localization docs still describe historical paths like /home/clawdie/astro-docs/ and direct host-webroot copy flows. Treat those pages as historical pipeline notes until they are rewritten. The current supported docs deployment path is the cms-jail workflow described on this page.