Publish Docs

Publish Docs (no new release)

Publishes a docs-only image to ghcr.io/vfarcic/dot-agent-deck-docs with a main-<short-sha> tag and updates site/helm/values.yaml so Argo CD picks it up. Does not create a release, version bump, binary build, Homebrew formula, Scoop manifest, or GitHub release.

What a publish builds

The site is generated by cargo xtask site (xtask/site) from docs/published.toml: the landing page from site/landing/, every manifest page as raw Markdown at /docs/<slug>.md, llms.txt and llms-full.txt, the images under site/static/img/ (docs/img is a symlink to it), and the redirects from the old Docusaurus URLs. There is no Node and no npm anywhere in it. .github/workflows/docs-publish.yml runs three jobs:

1. site-build checks out main with a read-only token and no secret, records the commit, and runs cargo xtask site site/build/public --nginx-redirects site/build/nginx-redirects.conf. site/build is uploaded as the docs-site artifact, which both deploy paths consume, so they publish the same bytes.
2. publish checks out that same commit with RELEASE_TOKEN (it fails at its first step if the secret is empty), downloads the artifact, and builds site/Dockerfile, which has no build stage: it copies site/build/public into nginx's root, site/build/nginx-redirects.conf to /etc/nginx/site-redirects.conf as an nginx config include, outside the served files, and site/nginx-default.conf as the server config. It pushes the image, sets image.tag in site/helm/values.yaml (and Chart.yaml's version and appVersion on the release path), commits that, and pushes the commit straight to main.
3. netlify-deploy deploys the same artifact's build/public to Netlify production with --no-build, after publish succeeds.

When to Use

• Docs / site changes have been merged to main and you want them live now.
• You don't want to cut a SemVer release just for documentation.

When NOT to Use

• You're cutting a versioned release — use /tag-release instead. The release workflow already publishes docs as part of the release via the same underlying docs-publish.yml workflow.
• You have un-released non-docs (code) changes that should also ship — cut a release.

Workflow

Step 1: Sync main locally

The workflow dispatches against origin/main, so make sure you know what's there:

git fetch origin
git checkout main
git pull --rebase origin main

If the user is in a worktree, fetch is enough — they don't need to switch branches; gh workflow run --ref main dispatches against the remote ref regardless of local checkout.

Step 2: Confirm there are docs/site changes since the last release

LAST_TAG=$(git tag --list 'v*' --sort=-v:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | head -1)
echo "Last release: ${LAST_TAG}"
git log --oneline "${LAST_TAG}..origin/main" -- docs/ site/ xtask/site/ src/published_docs.rs
git diff --stat "${LAST_TAG}..origin/main" -- docs/ site/ xtask/site/ src/published_docs.rs

xtask/site/ and src/published_docs.rs are the generator and the manifest parser, so a change there can change the published output even when no page did. A change under docs/develop/ changes nothing on the site; disregard it.

If there are no docs/site changes since the last release, inform the user and stop — there is nothing meaningful to publish.

Step 2b: Build the site locally (optional)

The same command the workflow runs, so a broken link or a manifest error shows up here rather than in the run. It needs only the Rust toolchain, and refuses an output directory that is not empty. Run it in a checkout at origin/main — the user's own, or a detached worktree at a disk-backed sibling path (CLAUDE.md rule 14, since it compiles the xtask crates), which you ask about before creating:

rm -rf site/build   # generated output, gitignored
cargo xtask site site/build/public --nginx-redirects site/build/nginx-redirects.conf

Skip it when the user has just done this themselves on that commit.