Skip to content
Clawdie Clawdie

Docs and tenant-site publishing

Docs and tenant-site publishing

Section titled “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

Section titled “Current model”

The current deploy shape is:

  • Host repo source: /home/<agent>/clawdie-ai/
  • Astro project in repo: bootstrap/cms/clawdie-docs/
  • Astro project in cms jail: /usr/home/<tenant>/<tenant>-docs/
  • Mounted host source in cms jail: /usr/home/<tenant>/<tenant>-docs-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

Section titled “Docs publishing”

Source of truth

Section titled “Source of truth”

For docs content, the source of truth is:

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

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

Day-to-day docs workflow

Section titled “Day-to-day docs workflow”
  1. Edit docs in docs/public/ on the host.
  2. Pull or update the host repo if needed:
Terminal window
git pull
  1. Build and deploy from inside the cms jail project:
Terminal window
cd /usr/home/<tenant>/<tenant>-docs
npm run deploy

That deploy flow runs:

  1. scripts/sync-host-config.mjs
  2. scripts/sync-public-docs.mjs
  3. scripts/generate-llms-files.ts for /llms.txt and /llms-full.txt
  4. astro build
  5. 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.

Machine-readable docs output

Section titled “Machine-readable docs output”

The docs build also emits two English-only root artifacts for external LLM consumers:

  • /llms.txt — a curated map of the public docs
  • /llms-full.txt — one concatenated context file built from the same public docs source

These are generated from docs/public/ during the normal docs prebuild path.

Strapi editorial flow

Section titled “Strapi editorial flow”

When docs-related content changes in Strapi:

Terminal window
cd /usr/home/<tenant>/<tenant>-docs
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

Section titled “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:

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

Example:

Terminal window
npm run publish-tenant-site -- --tenant atlas --site blog

What the command does

Section titled “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

Section titled “Current operator flow”
  1. Declare or update the site in infra/tenants.yaml
  2. If Strapi content changed, run:
Terminal window
cd /usr/home/<tenant>/<tenant>-docs
npm run export-strapi
  1. Review and commit the snapshot diff on the host
  2. From the host repo root, publish the site:
Terminal window
npm run publish-tenant-site -- --tenant <tenant> --site <site>
  1. Verify:
    • tenant home shows the site as available
    • the site host serves real content

Publish state meanings

Section titled “Publish state meanings”

Tenant-site publishing has 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 acceptable while publishing sites in batches.
  • 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

Section titled “What verify checks”

just setup -- --step verify checks tenant-site publishing directly.

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

Section titled “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

Section titled “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