Automation: separate documentation, Edge, and runtime release planes

This page is for maintainers. New users do not need to understand all CI/CD details to install herdr-mcp.

herdr-mcp intentionally separates automation into independent planes:

CopyDocumentation       Public Edge          Local Runtime
GitHub Pages         Cloudflare Worker    runtime generation A/B
     │                    │                     │
Human + agent docs    OAuth/MCP/WSS       fs/git/shell/Herdr

They share a repository, but not credentials, rollback boundaries, or failure domains.

Why separate release planes#

A normal fix should not accidentally change:

• public documentation;
• OAuth identity;
• Cloudflare routing;
• local runtime generation;
• ChatGPT tool contract.

The rule is simple: change the smallest plane required by the task.

GitHub Pages#

Workflow:

Copy.github/workflows/pages.yml

Site:

Copyhttps://whshang.github.io/herdr-mcp/

Build entry:

Copynpm run build:site

The site generator validates the logical document model, locale completeness, navigation and generated pages.

Pages serves both:

CopyHuman documentation

Remote planner policy

herdr_skill can use the published skill source and fall back to the bundled release copy when network access is unavailable. HERDR_SKILL_NETWORK=0 forces offline behavior.

CI#

Workflow:

Copy.github/workflows/ci.yml

CI proves that a commit does not break other planes. Typical gates include:

• dependency install;
• TypeScript build;
• documentation site build;
• runtime tests;
• Edge/frozen-contract tests;
• extension smoke tests;
• shell syntax checks;
• package dry-run;
• git diff --check.

The public MCP contract is intentionally more stable than runtime implementation. Production currently uses contract epoch 2 / 18 tools. Historical compatibility tests may exist, but normal runtime changes should not silently change the public catalog.

Cloudflare Edge deployment#

Workflow:

Copy.github/workflows/cloudflare-edge.yml

Edge automation manages the public control plane:

• Worker / Durable Object;
• OAuth;
• MCP relay;
• workstation routing;
• post-deploy health checks.

Deployment secrets belong in GitHub Environment/Secrets.

A normal Worker deployment should not automatically modify:

• Custom Domain;
• DNS;
• legacy Tunnel state;
• OAuth issuer;
• workstation identity;
• local runtime generation.

Domain and DNS mutations are separate operations with separate rollback evidence.

See Cloudflare Edge deployment and Cloudflare Edge credentials.

Local runtime automation#

Local releases use runtime generations instead of replacing the active process in place:

Copystable A
  ↓
candidate B
  ↓
health + contract gate
  ↓
activate
  ↓
keep rollback target

Common entry points:

Copybin/herdr-runtime-generation status
bin/herdr-self-update status
bin/herdr-self-update check

herdr-self-update automates candidate build, validation, activation and observation. It does not own:

• contract epoch migration;
• Edge deployment;
• OAuth issuer migration;
• DNS / Custom Domain changes.

See Runtime A/B.

Contract epoch migration#

A public MCP tool surface change is different from a runtime implementation update.

Copyruntime implementation upgrade
        ≠
public MCP contract migration

A contract migration affects ChatGPT tool snapshots and requires explicit evidence across local runtime, Link identity, public Edge and new conversation validation.

Browser extension release#

The extension is the continuity layer. It shares repository versioning but keeps separate trust boundaries.

Validation includes:

• manifest and JavaScript compatibility;
• Native Messaging host;
• workspace binding;
• Auto gates;
• progress/settled behavior;
• recovery/handoff;
• JSON → MCP bridge.

Real browser UAT is still required because Node tests cannot prove page behavior.

herdr_skill#

herdr_skill combines:

1. herdr-mcp project policy;
2. runtime / contract / generation context;
3. matching Herdr guidance.

It guides Web planner behavior. It does not replace CI, deployment scripts or runtime management.

herdr_methods remains the authority for the installed Herdr Socket API schema.

Release decision table#

What completion means#

A green workflow is not the final proof.

The corresponding runtime evidence is required:

• Pages: generated pages and links work;
• Edge: health + workstation + OAuth/MCP work;
• Runtime: active generation + real tool call + rollback target;
• Extension: real site binding/Auto/recovery smoke;
• Contract: a new conversation receives the expected tool snapshot.

Automation is valuable because it fixes verification and rollback boundaries, not because it removes every human decision.