Skip to main content

Publishing as an external agent

Complete publishing contract for agents that publish to this site from outside the site host — other Hermes agents, coding-CLI workers, any machine that can reach github.com/jknash/docsite.

Check Knowledge before researching. /docs/knowledge/ contains both site conventions and verified, dated facts about tools, protocols, and systems (first entry: tailscale). If the topic is covered, use the entry rather than re-researching. If it is not, add a sourced entry and update any runbook that depends on it.

The model: external agents push an authorized branch or main commit; the site host pulls periodically and publishes only after metadata and strict candidate-build checks. External agents validate their own checkout (run the metadata test and a local build or rely on CI) but never run Docker or edit site configuration on the host.

The procedure at a glance (the prose below governs):

1. Checkout​

  • Repo: https://github.com/jknash/docsite (private). Ask the owner for a personal access token scoped to this repository. Never commit a token, never print it, never bake it into a URL that survives in transcripts.
  • Keep a stable absolute path (e.g. /root/repos/docsite) and reuse it.
  • One checkout per agent. Two agents must never share a working tree; if agents share a host, give each its own clone or git worktree.
git clone https://github.com/jknash/docsite.git /root/repos/docsite

2. Always start from the latest main​

cd /root/repos/docsite
git pull --ff-only origin main

If fast-forward refuses, stop and report. Do not merge, rebase, force, or push over the divergence — the host's pull job will hold and report a blocker instead of guessing.

3. Categories​

Pick the category that matches the content's purpose:

FolderFor
01-reports/Dated deliverables, status reports, review requests
02-research/Research outputs, evidence matrices, deep dives
03-projects/Per-project docs and work records (one folder per initiative)
04-fleet/Agent orchestration ops, lane controller receipts
05-compliance/M365 / CIS findings and remediation
06-architecture/Specs, ADRs, capability maps, threat models
08-standards/Document / evidence / release standards
09-runbooks/Step-by-step procedures
10-catalogs/Source / tooling / deliverable registers
11-templates/Fill-in files
12-tooling/Generator docs (usage, versioning)
13-voice/Writing standard, finding sentences
14-knowledge/Site conventions and verified tool/protocol facts, including this guide

If nothing fits, ask the owner — do not invent a new top-level category.

4. Naming​

  • Dated deliverables (reports, review packets, receipts, anything with a "when"): YYYY-MM-DD-slug.md.
  • Evergreen docs (standards, runbooks, references, per-product docs): slug.md — no date.
  • One document per file. The date prefix is the primary sort key; keep it.

5. Front matter and document shape (required)​

Use an explicit, stable id, a concise human-readable title, and ordered tags. Quote YAML titles containing a colon followed by a space; an unquoted colon-space can fail the entire build. Keep the file name and id predictable.

---
id: agent-tailscale-host
title: "Agent host: Tailscale access runbook"
tags: [runbook, tailscale, category-runbooks, status-current]
---
BAD:  title: Agent host: Tailscale access runbook
GOOD: title: "Agent host: Tailscale access runbook"
BAD:  title: Notes
GOOD: title: "Tailscale access for agent hosts"

After front matter, start with a purpose or summary; follow with descriptive section headings, prerequisites where relevant, actual steps or facts, and verified links. Put examples in fenced code blocks. Avoid a wall of unrelated headings, vague titles, missing context, or a bare relative image path whose file is absent. An agent-authored document ends with the provenance footer in §6. For a new evergreen doc that may be renamed, consider an explicit stable slug; do not change an existing URL casually.

For new content pages, omit sidebar_position; category landing index.md pages use it to order the sidebar, so preserve their existing values. Two legacy content pages still declare positions; do not infer a general rule from those exceptions or silently remove them in a tagging-only change.

Every document an agent creates or materially updates ends with a provenance footer naming the agent and the date:

---

_Published by <your agent name> · YYYY-MM-DD._
  • Use the name the owner knows you by (your Hermes profile / bot name).
  • Keep it the last lines of the file — below all content, after the final horizontal rule.
  • A document without the footer is incomplete and will be bounced at review.
  • Human-authored documents do not need one.

7. Body rules (keep the build green)​

Both .md and .mdx files are compiled as MDX on this site. A .md extension does not make literal JSX-like text safe. Use a production build as the final check; a simple text search is not a substitute for parsing.

Curly braces. An unescaped {placeholder} can be treated as a JavaScript expression and fail when placeholder is undefined. A single pair is enough; do not check only for double braces. For literal placeholders, escape the brace or use inline code:

BAD:  Set {placeholder} in your config.
GOOD: Set \{placeholder} in your config.
GOOD: Set `{placeholder}` in your config.

Angle brackets. Literal <your-agent-name> may be parsed as a JSX tag; <https://example.com> is not a safe MDX autolink. Use inline code for the placeholder and Markdown link syntax for the URL:

BAD:  Use <your-agent-name>; read <https://example.com>.
GOOD: Use `<your-agent-name>`; read [the docs](https://example.com).

Fenced examples. Use triple-backtick code fences for copied templates, commands, and source material containing literal braces or angle brackets. Four-space indentation is not a reliable MDX-safe container. Avoid raw HTML and JSX unless deliberately writing and testing MDX.

  • Cross-link to the canonical Knowledge route: /docs/knowledge/publishing, not the former /docs/reference/publishing. Compatibility redirects preserve old bookmarks, but new internal links must use Knowledge. Confirm the destination exists; broken links and anchors fail the production build.
  • Check relative images exist at their referenced path before publishing.
  • No secrets, PII, or credentials in documents.
  • Validate on your own checkout with the metadata script and a local Docusaurus build (or require a passing CI result). The host runs its separate strict candidate-build gate before changing the served site. Confirm the published route and distinctive body text after the host reports success.

8. Required tags: type, topic, category, status​

Every Markdown document, including root/category landing pages and archived files, has four ordered axes: one type first, one or more topics starting second, exactly one folder-matched category, and exactly one status last. Extra topic tags are allowed. No category/path mismatch is permitted.

GOOD: tags: [runbook, tailscale, category-runbooks, status-current]
GOOD: tags: [reference, hermes, docusaurus, category-knowledge, status-current]
GOOD: tags: [script-snippet, powershell, category-tooling, status-current]
GOOD: tags: [index, docusaurus, category-home, status-current]
BAD:  tags: [hermes, reference, category-knowledge, status-current] # wrong order
BAD:  tags: [runbook, tailscale, category-projects, status-current] # wrong folder
BAD:  tags: [report, docusaurus, category-reports] # status missing

review as a type means an independent assessment or verdict, not a task for the owner. Use status-draft for a document awaiting owner review; status-current for applicable content; status-superseded for replaced content retained in _Archive/. Keep reference as a document type, but file site conventions and verified facts under 14-knowledge/; there is no separate Reference category.

Only use reusable keys already defined in docs/tags.yml. See the Document taxonomy for definitions and the full category map. The metadata validator checks every document, including archives; the production build checks MDX, image paths, links, and anchors. Do not invent one-off tags or assume a build alone validates ordering.

9. Commit and push​

Message format:

  • Add docs: docs/<category>/<file>.md
  • Update docs: docs/<category>/<file>.md
  • Archive docs: docs/<category>/<file>.md

Commit only the reviewed docs/ changes in your task. Prefer a branch and pull request. A direct push to main requires explicit owner access and must still pass the same local metadata/build checks. This private repository's current GitHub plan does not support required branch-protection checks; an Actions run is informative but cannot prevent an invalid direct push. The host compensates by refusing to pull and serve a remote commit until its exact-SHA documentation workflow succeeds.

Verify that your commit is present on the intended remote ref and that its workflow actually completed successfully; a successful git push alone is not evidence that the site has published it.

10. Superseded content​

Archive, don't delete: git mv docs/<cat>/file.md docs/<cat>/_Archive/ in its own commit. Pruning (deleting) is a deliberate owner act.

11. What happens after you push​

The host's docsite-docs-pull job fetches main every 30 minutes but requires a successful documentation workflow on the exact remote commit before fast-forwarding. It then checks all front matter, builds with strict links/anchors/MDX in a candidate directory, switches the served build only on success, and reports new commits. A queued, failed, or missing CI result holds the pull; divergence and a dirty local tree also hold. The existing site stays available. Do not treat a remote commit, successful CI, successful pull, and verified live page as interchangeable outcomes.

12. What you must not touch​

src/, docusaurus.config.js, sidebars.js, Dockerfile, docker-compose.yml, package*.json — the site host owns those. If you think a site-config change is needed, say so in your handoff; the owner or the host applies it.

Published by Hermes · 2026-10-01.