Publish Docs

Sync the active company's published documentation site — the standalone, user-facing docs site that lives in its own repo and deploys to its own URL (e.g. docs.{company}.com built from repos/public/{company}-docs) — so it reflects what actually shipped.

This command is a company-agnostic dispatcher. It does not itself know how any one company builds or publishes its docs site. It resolves the active company, finds that company's docs-site sync skill, and runs it foreground. Companies without a published docs site are a clean no-op.

Scope boundary (read this first)

There are two distinct documentation layers, and this command owns exactly one:

Layer	Owner	What it touches
In-repo docs	document-release	README.md, CLAUDE.md, architecture docs, INDEX.md, CHANGELOG — docs that live alongside the code
Published docs site	this skill	the standalone docs-site repo that builds and deploys to a public URL

document-release never reaches into a separate docs-site repo. This command is that missing half. /ship runs both, in order, as its final foreground step.

When NOT to run

• The change did not ship anything material to a product users see (internal refactor, HQ-core plumbing, tooling). Publishing docs for a no-op change is churn.
• No company is resolvable. This command requires a company anchor; it never guesses across tenants.

Step 0: Resolve Company

1. Bind the active company the same way every HQ command does: explicit mention → cwd → the repo's owning company in companies/manifest.yaml → handoff. Never guess or cross tenants.
2. Announce: Publishing docs site for: {company name}

If no company resolves, stop and say so — do not proceed unanchored.

Step 1: Discover the Company's Docs-Site Sync Skill

A company opts in to docs-site publishing in one of two ways. Check in this order and use the first that matches:

1. Explicit manifest declaration. Read the company's entry in companies/manifest.yaml. If it declares:

   {co}:
     docs_site:
       sync_skill: {co}:sync-docs   # skill to invoke
       repo: repos/public/{co}-docs # optional, informational
       url: https://docs.example.com # optional, informational
   

   use docs_site.sync_skill as the skill to run.

2. Convention. If no manifest declaration, check whether the company ships a docs-site sync skill by convention at companies/{co}/skills/sync-docs/SKILL.md. If present, the skill to run is {co}:sync-docs.

3. Neither → clean no-op. If the company declares no docs_site.sync_skill and has no companies/{co}/skills/sync-docs/, report and exit successfully:

   publish-docs: no published docs site configured for {company name} — skipping.
   (To enable: add a `sync-docs` skill under companies/{co}/skills/, or a
    docs_site.sync_skill entry in companies/manifest.yaml.)
   

   Exit 0. This is the expected path for companies without a public docs site, and it is why /ship can call this unconditionally without going red.

Do NOT fabricate or hardcode any specific company's skill name. The only company-specific knowledge lives in that company's own skill/manifest.

Step 2: Dispatch (foreground)

Invoke the resolved docs-site sync skill in the foreground via the Skill tool (e.g. Skill(skill: "{co}:sync-docs")). Never background this — the whole point is that published docs are live and verified before the caller reports done.

The company skill owns everything site-specific: deciding whether the shipped change is material to the public docs, editing the affected pages, building the docs-site repo (anchored with an explicit absolute cd /abs/repo && ... per hq-anchor-repo-build-cwd), publishing, and verifying the pages live. This command does not second-guess that skill's build/publish steps.

Pass through any context the caller provided (the shipped diff, PR refs, project slug) so the company skill can judge materiality without re-deriving it.

Step 3: Report

Relay the company skill's outcome in one plain line, keeping any live URL it returns:

Docs site: {published — <url> | no material change, nothing to publish | skipped — none configured}

If the company skill failed, surface the failure plainly — do NOT swallow it. When called from /ship, a docs-site failure is reported but does not retroact the ship's merged/deployed/smoked status (docs are not in ship's done-criteria); the caller decides whether to heal or hand off the docs failure.

Rules

• Company isolation — resolve exactly one company; only touch that company's docs site, repo, and credentials. Cross-company docs publishing is a category-1 bug.
• Foreground only — never dispatch the docs-site sync as a background job.
• Dispatcher, not implementer — all site-specific build/publish/verify logic lives in the company's own skill. Keep this command generic.
• Clean no-op for unconfigured companies — absence of a docs site is a success, not an error, so callers (like /ship) stay green.
• Anchor builds — if you ever run a build directly, anchor it with an explicit absolute cd /abs/repo && ... (policy hq-anchor-repo-build-cwd); a green build is not proof you built the right repo.
• Never guess credentials or targets — read them from the resolved company's policies/manifest only.