clawdie/colibri
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 31
colibri/docs/guide/operate/docs-publishing.md
Sam & Claude 1f393af09c docs(guide): rewrite colibri.md for v0.12 + final language polish 
- colibri.md: complete rewrite — was TypeScript "event fabric" with pi-centric
  ingestion modules, proof gates, Herdr evaluation. Now describes the actual
  v0.12 Rust control plane: crate map, agent model (zot/pi), mother MCP flow,
  links to wiki decision pages.
- "broken" → "inconsistent" (docs-publishing), "compromised" (install),
  "not suitable" (sdk-deep-dive)
- Zero remainders: no kill, smoke, fake, hacky, TODOs, stale pi patterns
2026-06-26 09:38:49 +02:00

5.4 KiB
Raw Permalink Blame History

title description
Docs and tenant-site publishing Current operator workflow for Astro/Starlight docs deploys and manual tenant-site publishing from the cms jail.

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-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

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

  1. Edit docs in docs/public/ on the host.
  2. Pull or update the host repo if needed:
git pull
  1. Build and deploy from inside the cms jail project:
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

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

When docs-related content changes in Strapi:

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

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 atlas --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>-docs
npm run export-strapi
  1. Review and commit the snapshot diff on the host
  2. From the host repo root, publish the site:
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

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 inconsistent.

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

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