Add non-ratified 'doc' mode to the template

[Bill Traynor (wmat)]

Summary

Adds a first-class mode switch so docs-spec-template can serve non-ratified
RISC-V documentation (e.g. docs-dev-guide)
as well as ratified specifications. A single committed .docmode file selects
spec (today's behavior, byte-for-byte) or doc. Absent ⇒ spec, so every
existing spec repo is unaffected.

doc mode keeps the ARC-form PDF, the Makefile HTML target, and the Antora site,
but strips the ratification layer: no milestone phases, no "Document State"
preface, no spec-state cover banner, no milestone version-bot PRs.

Closes #110.

How it works

.docmode (self-documenting: value on line 1, # comments below) is read by
release-info.sh, the Makefile, stamp-antora-version.sh, and CI — each parses
the first non-comment token, so a missing/empty file resolves to spec.

Concern	spec (default)	doc
ARC-form PDF / Makefile HTML / Antora site	✅	✅
Version scheme	semver tags → milestone phase gates	semver tags + build date, no phases
"Document State" preface + spec-state banner	✅	❌ omitted
Milestone version-bot / milestone PRs	✅	❌ inert (plain patch bumps)
SPEC_STATE.md, ARC_SUBMISSION.md	apply	not used

Discoverability & reversibility

• README.adoc gains a "First step — choose your mode" setup callout (the admin
  creating the repo sees it), and .docmode self-documents.
• make set-mode MODE=<spec|doc> switches an existing repo in place — flips
  .docmode and reconciles antora.yml's page-phase* block, then re-stamps. A
  mis-selection is a reversible PR, not a repo recreation.

Files

.docmode (new), scripts/set-mode.sh (new), scripts/release-info.sh,
scripts/stamp-antora-version.sh, Makefile, src/spec-sample.adoc,
modules/ROOT/pages/index.adoc, .github/workflows/{build-pdf,version-bot}.yml,
README.adoc, ANTORA.md, MIGRATION.md.

Verification (local, both modes)

• spec-mode regression: release-info.sh all output and a re-stamp of
  antora.yml are identical to main; PDF still renders "Document State".
• doc mode: PDF and Makefile HTML build clean and omit "Document State";
  cover renders with no phase banner and no trailing : <display>.
• stamp: doc-mode descriptor (no page-phase*) stamps cleanly; spec-mode
  stamp on a phase-less file fails loudly (exit 3) rather than silently.
• set-mode: round-trips spec↔doc idempotently; MODE guards fire.
• pre-commit hooks pass; bash -n clean.

Out of scope

Migrating the real docs-dev-guide repo — that lands as a separate PR in that
repo; it is the worked example in MIGRATION.md here.

🤖 Generated with Claude Code

[Rafael Sene (rpsene)]

Bill Traynor (@wmat) doc mode is only verified locally. Since the template now ships two modes, add a doc-mode smoke build to CI so a future change can't silently break it. Also add a comment in set-mode.sh noting it assumes 4-space antora.yml indentation, since that awk is the fragile part.

[Bill Traynor (wmat)]

Thanks for the review — both addressed in a8fd252.

Doc-mode CI smoke build (build-pdf.yml): new PR-only doc-mode-smoke job so a change that only breaks doc mode can't merge green. It builds the doc path via a DOC_MODE=doc env override (never edits the committed .docmode) and asserts a PDF lands, then round-trips set-mode.sh (spec → doc → spec) asserting the page-phase* block is stripped on doc and restored on spec — which directly exercises the fragile awk. Gated if: github.event_name == 'pull_request' so it stays out of the release/tag and site-stamp jobs.

set-mode.sh note: added a FRAGILE comment that the reconcile awk hard-codes the template's 4-space antora.yml indentation (matching stamp-antora-version.sh), what to update if it's ever reindented, and that CI round-trips it.