publish · diff
git:20261007.a8e832e to git:20261007.bc42916
19 added, 27 removed. Audit A to A.
---
name: publish
- description: Build a local HTML preview of an openEHR specification component via the AA_GLOBAL publisher
+ description: Build a local HTML preview of an openEHR specification component with the published AA_GLOBAL publishing image
argument-hint: "<component, e.g. RM>"
allowed-tools:
- - "Bash(./specifications-AA_GLOBAL/bin/spec_publish.sh *)"
- "Bash(docker run * ghcr.io/openehr/asciidoctor *)"
- Read
- Glob
disable-model-invocation: true
---
Build a local HTML preview of the component named in `$ARGUMENTS` (for example `RM`, `BASE` or `AM`)
- with the publisher in `specifications-AA_GLOBAL`. The publisher builds a whole component, not a single
- spec. This is the preview step of the `openehr-specs:authoring` skill. It never tags, commits, or
- deploys a release; that is the `governance` skill.
-
- If `$ARGUMENTS` is empty, ask which component and stop: without one, the script rebuilds every sibling
- `specifications-*` repo.
-
- The script prints `generated <file>` and exits 0 even when `asciidoctor` is missing or failed. Confirm
- the outputs (steps 2 and 4) instead of trusting that line.
+ with the published `ghcr.io/openehr/asciidoctor` image. This is the preview step of the
+ `openehr-specs:authoring` skill: it builds a whole component as the `development` release and never
+ tags, commits, or deploys (that is `governance`). If `$ARGUMENTS` is empty, ask which component and
+ stop: the image takes exactly one.
- 1. Work from the parent directory that holds the sibling `specifications-AA_GLOBAL/` and
- `specifications-<component>/` checkouts. If either is missing, say which and stop. Run
- `which asciidoctor jq bc`: the script needs all three. If one is missing, name it and use the Docker
- fallback in step 3; if `which docker` finds nothing either, report both and stop.
+ 1. Work from the parent directory that holds the sibling `specifications-AA_GLOBAL/` (the image reads
+ the boilerplate and references from it) and `specifications-<component>/` checkouts. If either is
+ missing, say which and stop. If `which docker` finds nothing, say Docker is required and stop.
2. Snapshot the outputs: `stat -c '%Y %n' specifications-<component>/docs/*.html` (ignore "No such
file"; use `ls -l` where `stat -c` is unavailable).
- 3. Build:
+ 3. Build. The entrypoint is `spec_publish.sh -f -r -v -t -q -l`, so the first argument is the release:
```bash
- ./specifications-AA_GLOBAL/bin/spec_publish.sh -f -v $ARGUMENTS
- # fallback when a tool is missing:
- docker run -u $(id -u):$(id -g) -v "$(pwd):/documents/" ghcr.io/openehr/asciidoctor development $ARGUMENTS
+ docker run --rm -u $(id -u):$(id -g) -v "$(pwd):/documents/" ghcr.io/openehr/asciidoctor development $ARGUMENTS
```
- 4. Verify. Glob `specifications-<component>/docs/*/master.adoc`: each needs a rebuilt
+ 4. Verify, because the build prints `generated <file>` and exits 0 even when includes are missing or
+ `asciidoctor` failed. Glob `specifications-<component>/docs/*/master.adoc`: each needs a rebuilt
`docs/<dir>.html` beside it, plus `docs/index.html` when `docs/index.adoc` exists. Repeat the `stat`
- command. A file that is missing, or whose time did not change, was not built: list each as
- `NOT BUILT` and report the build as failed.
- 5. Report where the HTML landed and every Asciidoctor warning or error verbatim (unresolved
- attributes, missing includes, missing images). On failure, summarise the first actionable error and
- point to `authoring` (includes, attributes) or the `xref-auditor` subagent (cross-references).
-
- Never pass a release label (`-l Release-N.N.N`); releasing belongs to `governance`.
+ command; a file that is missing or unchanged is `NOT BUILT`. Any `ERROR` or `include file not found`
+ log line (for example `{pkg}…` class tables) also fails the build. An `INFO` line, such as a possible
+ invalid bibliography reference, does not.
+ 5. Report where the HTML landed and every error or warning verbatim. On failure, summarise the first
+ actionable error and point to `authoring` (includes, attributes) or the `xref-auditor` subagent
+ (cross-references). The build rewrites the tracked `docs/*.html` artefacts: tell the user, and do not
+ stage them.