diff --git a/CHANGES.md b/CHANGES.md
new file mode 100644
index 0000000..9dd378e
--- /dev/null
+++ b/CHANGES.md
@@ -0,0 +1,38 @@
+# Changes
+
+## 2026-06-08 — Antora structure and documentation site guidance
+
+### New files
+
+- `src/antora-structure.adoc` — New section documenting the Antora-based repository layout used by RISC-V specification repositories. Covers `antora.yml`, `modules/ROOT/pages/`, `modules/ROOT/nav.adoc`, `modules/ROOT/images/`, and how to register a specification with the RISC-V documentation site by submitting a pull request to [riscv-admin/antora-dev.riscv.org](https://github.com/riscv-admin/antora-dev.riscv.org). Includes content-source entry format, chapter numbering rules configuration, branch naming conventions, and Antora installation instructions.
+
+### Modified files
+
+**`src/docs-dev-guide.adoc`**
+- Added `include::antora-structure.adoc[]` between `authoring.adoc` and `a_few_basics.adoc`.
+
+**`src/authoring.adoc`**
+- Updated repository reference from `docs-templates` to `docs-spec-template`.
+- Replaced stale `asciidoctor book_header.adoc` quick-build command with the correct entry point (`asciidoctor modules/ROOT/pages/spec-sample.adoc`) and a `make` alternative.
+- Updated description of template repo to reflect Antora-based directory structure.
+
+**`src/a_few_basics.adoc`**
+- Updated two references to `book_header.adoc` (lines 91 and 334) to `modules/ROOT/pages/spec-sample.adoc` in the docs-spec-template repo.
+
+**`src/build-infrastructure.adoc`**
+- Added `=== Source directory` subsection noting that `SRC_DIR` is now `modules/ROOT/pages/` and cross-referencing the antora-structure section.
+- Added `[[spec-types]]` subsection distinguishing ISA specifications (authored on a branch/fork of riscv-isa-manual) from non-ISA specifications (authored in an autonomous repository using docs-spec-template).
+- Added `[[spec-lifecycle]]` section defining the four specification states (Draft, Stable, Frozen, Ratified) with `:revremark:` examples and a link to `riscv.org/spec-state`.
+- Documented that state advancement is entirely manual — no automation promotes a specification between states.
+- Documented the non-ISA release process using the `workflow_dispatch` GitHub Actions trigger, including the `revision_mark` input and a note on keeping it consistent with `:revremark:` in the source.
+- Documented that ISA specification state is managed within the relevant chapter(s) of the riscv-isa-manual branch where the author is working.
+
+**`src/intro.adoc`**
+- Added `[[getting-help]]` subsection consolidating help resources: `sig-documentation` mailing list, `help@riscv.org`, docs-dev-guide GitHub issues, and antora-dev.riscv.org GitHub issues.
+
+**`local_build.md`**
+- Updated `## AsciiDoc book headers and styles` section to reference `modules/ROOT/pages/spec-sample.adoc` as the document entry point and `docs-resources/global-config.adoc` for shared attributes.
+- Updated `## Create and name a new .adoc file` to reflect the Antora workflow: new files go in `modules/ROOT/pages/`, are included in `spec-sample.adoc` for the PDF build, and registered in `modules/ROOT/nav.adoc` for the Antora site.
+- Updated `## HTML build` section to use `make` and the correct entry point (`modules/ROOT/pages/spec-sample.adoc`) in place of stale `book_header.adoc` references.
+- Added `## Antora site build` section covering `make antora`, output location, and Antora installation (`npm install -g antora`).
+- Added `## Run a local Kroki server for diagrams` section with the Docker run command (`docker run -d -p 9870:8000 yuzutech/kroki`), a stop command, and a note that the dev playbook is already configured for `localhost:9870`.
diff --git a/local_build.md b/local_build.md
index 0ce4a3c..e63e2b0 100644
--- a/local_build.md
+++ b/local_build.md
@@ -218,6 +218,26 @@ wavedrom-cli
 
 WARNING: For the MacOS, if you upgrade from a prior version to Big Sur, you must reinstall first the NPM and then the NPM version of the wavedrom-cli.
 
+## Run a local Kroki server for diagrams
+
+The RISC-V documentation site uses [Kroki](https://kroki.io) to render diagrams (including WaveDrom, Bytefield, Graphviz, and others) server-side. The dev playbook at `antora-dev.riscv.org` is configured to reach a local Kroki instance on port 9870.
+
+Start the Kroki server with Docker:
+
+```cmd
+docker run -d -p 9870:8000 yuzutech/kroki
+```
+
+The `-d` flag runs it in the background. The container will restart automatically on subsequent Docker starts unless explicitly stopped.
+
+To stop it:
+
+```cmd
+docker stop $(docker ps -q --filter ancestor=yuzutech/kroki)
+```
+
+The dev playbook already has `kroki-server-url: http://localhost:9870` set in its `asciidoc.attributes`, so no additional configuration is needed once the container is running.
+
 ## Graphviz is used for diagrams in some appendices
 
 To support graphviz on the Mac, use brew
@@ -264,47 +284,75 @@ You can then add a bibliography to your appendices and use bibtex conventions to
 Details of how to work with bibtex and the RISC-V bibliogrpahy are in the example.pdf file.
 
 
-## AsciiDoc book headers and styles
+## AsciiDoc document header and styles
 
-Attributes in the book headers for RISC-V AsciiDoc content control aspects of the pdf build. Together with the `risc-v_spec-pdf.yml` file, they enable, among other things, numbered headings, a TOC, running headers and footers, footnotes at chapter ends, custom fonts, admonitions, an index, and an optional colophon.
+Attributes in the document header for RISC-V AsciiDoc content control aspects of the pdf build. Together with the `docs-resources/themes/riscv-pdf.yml` file, they enable, among other things, numbered headings, a TOC, running headers and footers, footnotes at chapter ends, custom fonts, admonitions, an index, and an optional colophon.
 
-In addition, properties in the book header within this repo point to the `images` directory and also the `resources/riscv-spec.bib` file that contains the RISC-V `bibtex` entries for use in creating a bibliography as one of the appendices.
+The entry point for the build is `modules/ROOT/pages/spec-sample.adoc`. This file contains the document header attributes and uses `include::` directives to pull in the chapter files. The `docs-resources/global-config.adoc` submodule file provides shared attributes such as `:company:` and `:doctype:`.
 
-For shorter documents, you have the option of using a report header, however, we have not yet provided branding for it.
+NOTE: The header is already in the template. The only changes you normally need to make are to update `:revnumber:`, `:revremark:`, and author metadata, then add chapter files using `include::chapter.adoc[]` in the order you want them to appear.
 
-NOTE: The headers are already in the template files. The only changes you normally need to make are to add chapter-sized sections in using the syntax `include::filename.adoc[]` in the order by which you want them to appear.
+## Create and add a new chapter file
 
-## Create and name a new .adoc file
-
-- In your text editor, create a new file.
-- Assign a name and save with the .adoc extension.
-- In the first line, add `[file_name]` (using a meaningful string for the filename) and in the second line, use a double "==" to indicate a topic heading, add some content, and save the file with an `.adoc` file extension.
-- In the header file, add `include::file_name.adoc` and save it.
-
-NOTE: Blank lines are not allowed in between the `include::file_name.adoc` files.
+- In your text editor, create a new file in `modules/ROOT/pages/`.
+- Assign a meaningful name and save it with the `.adoc` extension.
+- Begin the file with a section heading (`==`) rather than a document title (`=`), since it will be included into `spec-sample.adoc`.
+- Add an `include::chapter-name.adoc[]` line in `modules/ROOT/pages/spec-sample.adoc` in the position where you want the chapter to appear.
+- Add an `xref:chapter-name.adoc[Chapter Title]` entry to `modules/ROOT/nav.adoc` so the chapter appears in the Antora site navigation.
 
 ## HTML build
 
 Building in HTML is a good way to check that your content under development builds properly.
 
-As soon as you have installed Asciidoctor, you can build HTML content from any `.adoc` file on your own machine--simply CD into the directory that contains your `.adoc` files and run the following:
+The simplest approach from the repository root is:
+
+```cmd
+make
+```
+
+This builds both PDF and HTML output to the `build/` directory, using Docker if available or native tooling otherwise.
+
+To build HTML only without the Makefile, run:
+
+```cmd
+asciidoctor modules/ROOT/pages/spec-sample.adoc
+```
+
+For pdf output without the Makefile, cd into the repository root and use:
+
+```cmd
+asciidoctor-pdf -r asciidoctor-mathematical -a mathematical-format=svg \
+  -r asciidoctor-bibtex -r asciidoctor-diagram \
+  -a pdf-theme=docs-resources/themes/riscv-pdf.yml \
+  -a pdf-fontsdir=docs-resources/fonts/ \
+  modules/ROOT/pages/spec-sample.adoc
+```
+
+ALERT: When copying/pasting commands for the CLI on the Windows OS, check that no substitutions are being made. We have seen the `=` get replaced with a `#`, causing an error message about fonts.
+
+## Antora site build
+
+To preview how the specification will appear as a multi-page HTML site (as it will be published on the RISC-V documentation site), use:
 
 ```cmd
-asciidoctor any_file_name.adoc
+make antora
 ```
-This generates a file named `any_file_name.html`.
 
-For pdf output, cd into this cloned directory and use this command:
+Output is written to `build/site/`. This requires Node.js 18+ and either `antora` on your PATH or `npx` available.
+
+### Install Antora
 
 ```cmd
-asciidoctor-pdf -r asciidoctor-mathematical -a mathematical-format=svg -r asciidoctor-bibtex -r asciidoctor-diagram book_header.adoc -a pdf-style=resources/themes/riscv-pdf.yml -a pdf-fontsdir=resources/fonts/
+npm install -g antora
 ```
 
-This generates a file named `book_header.pdf` that makes use of the graphics, styles, and fonts that is identical to example.pdf.
+Verify:
 
-ALERT: When copying/pasting commands for the CLI on the Windows OS, check that no substitutions are being made. We have seen the '=' get replaced with a '#', causing an error message about fonts.
+```cmd
+antora --version
+```
 
-For your own content, change the name of the header file to a meaningful file name, and change the `include::filename.adoc` as needed.
+If you prefer not to install globally, `make antora` will automatically fall back to `npx antora` if `antora` is not on your PATH.
 
 ## AsciiDoc  and Asciidoctor toolchain documentation
 
diff --git a/src/a_few_basics.adoc b/src/a_few_basics.adoc
index 404c214..e9ec6f5 100644
--- a/src/a_few_basics.adoc
+++ b/src/a_few_basics.adoc
@@ -1,10 +1,7 @@
 [[a_few_basics]]
 == AsciiDoc basics
 
-pseudoinstruction
-pseudo-instruction
-
-AsciiDoc is fully documented, and its documentation is actively maintained. This document contains some information on AsciiDoc markup to get you started.
+AsciiDoc is fully documented, and its documentation is actively maintained. This document has information about AsciiDoc markup to get you started.
 
 For details and additional options, see:
 
@@ -14,7 +11,7 @@ For details and additional options, see:
 
 In addition, you can ask questions in <https://asciidoctor.zulipchat.com/>
 
-Best practice is to test the PDF build frequently to ensure that you have not accidentally introduced something that breaks the build.
+Best practice is to test the PDF build often to ensure that you have not accidentally introduced something that breaks the build.
 
 [NOTE]
 ====
@@ -25,7 +22,7 @@ Send questions to help@riscv.org.
 
 In AsciiDoc, normal paragraphs do not require markup.
 
-To create a new paragraph, put a space after the previous line of text and continue.
+To create a new paragraph, put a space after the earlier line of text and continue.
 
 ==== Basics of blocks and indents
 
@@ -33,12 +30,12 @@ To create a new paragraph, put a space after the previous line of text and conti
 
 * You can add indented, explanatory paragraphs to lists.
 +
-Add a `+` directly above the line of text that you want to be indented within the list.
+Add a `+` directly preceding the line of text that you want to indent within the list.
 * Another point.
 +
 Using the `+` to create an indented paragraph works only within the context of a numbered or bulleted list.
 
-AsciiDoc/Asciidoctor supports code blocks with syntax highlighting for many languages. You can use either periods or dashes to indicate code blocks, and use macros to indicate that the block contains code in the specified language, as in the following example:
+AsciiDoc/Asciidoctor supports code blocks with syntax highlighting for many languages. You can use either periods or dashes to indicate code blocks, and use macros to indicate that the block has code in the specified language, as in the following example:
 
 
 [source,adoc]
@@ -88,11 +85,11 @@ The following example is a valid sequence of headers.
 Index
 ```
 
-NOTE: Settings in the header file (`book_header.adoc` in the docs-templates repo) trigger auto-generation of Appendix prefixes and of the Index (among other things).
+NOTE: Settings in the header file (`modules/ROOT/pages/spec-sample.adoc` in the docs-spec-template repository) trigger auto-generation of Appendix prefixes and of the Index (among other things).
 
 === Lists
 
-Unordered lists are created with the `*` before the list item. Ordered lists require a `.` Add a space between any supporting text at the beginning of a list.
+Create unordered lists with the `*` before the list item. Ordered lists require a `.` Add a space between any supporting text at the beginning of a list.
 
 ==== Unordered list
 
@@ -167,7 +164,7 @@ Example output:
 .. second nested item
 . back to original level.
 
-You can also create an unordered list that contains a nested ordered list (or an ordered list that contains a nested unordered list).
+You can also create an unordered list that has a nested ordered list (or an ordered list that has a nested unordered list).
 
 [source,adoc]
 ----
@@ -249,9 +246,9 @@ Follow these general rules when you create a table.
 
 * Avoid tables in the middle of lists.
 * Do not use tables to lay out a page. For example, if you have a long list of items, do not use a 2 column table to save space. The information should make sense side by side.
-* Do not create a table that has a single row or a single column, unless you are following a previous layout. For example, if each section in a chapter includes a table of options, then use a table even if one of the sections has only a single option.
+* Do not create a table that has a single row or a single column, unless you are following an earlier layout. For example, if each section in a chapter includes a table of options, then use a table even if one of the sections has only a single option.
 * Always use table headers and captions to make your tables more accessible.
-* Use introductory sentences for your table. For example, "The following table contains the options for the CSR." You can use either a period or a colon for your introductory sentence.
+* Use introductory sentences for your table. For example, "The following table has the options for the CSR." You can use either a period or a colon for your introductory sentence.
 * Do not refer to the "table above" or the "below table". Use words such as "The following table" or "The preceeding table".
 
 [WARNING]
@@ -331,7 +328,7 @@ Either table renders with table headers.
 
 ==== Table captions
 
-The `book_header.adoc` file in the docs-templates repo sets the `full` cross-reference attribute to enable captions to display from targets in the anchors. This ability allows you to set captions for tables, blocks, and illustrations. If you do not provide a caption, Asciidoctor defaults to the _basic_ cross reference style.
+The `modules/ROOT/pages/spec-sample.adoc` file in the docs-spec-template repository sets the `full` cross-reference attribute to enable captions to display from targets in the anchors. You can set captions for tables, blocks, and illustrations. If you do not offer a caption, Asciidoctor defaults to the _basic_ cross-reference style.
 
 To set a caption for a table or image, use the pattern as follows:
 
@@ -360,7 +357,7 @@ kind of trap.
 .Characteristics of traps.
 [cols="<,^,^,^,^",options="header",]
 |===
-| |Contained |Requested |Invisible |Fatal
+| |Contained |Requested |Invisible |Unrecoverable
 |Execution terminates |No |Nolatexmath:[$^{1}$] |No |Yes
 |Software is oblivious |No |No |Yes |Yeslatexmath:[$^{2}$]
 |Handled by environment |No |Yes |Yes |Yes
@@ -369,7 +366,7 @@ kind of trap.
 
 ==== AsciiDoc tables from CSV data.
 
-AsciiDoc tables can also be created directly from CSV data. Set the format block attribute to `csv` and insert the data inside the block delimiters directly:
+You can also create AsciiDoc tables directly from CSV data. Set the format block attribute to `csv` and insert the data inside the block delimiters directly:
 
 [source,adoc]
 ----
@@ -381,7 +378,7 @@ The Lumineers,Ho Hey,Folk Rock
 |===
 ----
 
-The previous example renders as follows:
+The prior example renders as follows:
 
 [%header,format=csv]
 |===
@@ -391,7 +388,7 @@ The Lumineers,Ho Hey,Folk Rock
 |===
 
 
-There are numerous formatting options available. While some of the property settings are cryptic, they can be quite useful. There are numerous examples available at https://asciidoc.org/newtables.html. Here one example of what can be done with spans alignment in tables from that page:
+There are many formatting options available. While some of the property settings are cryptic, they can be quite useful. There are examples available at https://asciidoc.org/newtables.html. Here is an example showing spans alignment in tables from that page:
 
 [source,adoc]
 ----
@@ -416,7 +413,7 @@ Which renders as follows:
 
 The following example is code for a numbered encoding table with link target.
 
-NOTE: Annotations have been added to the code to illustrate their use.
+NOTE: We have added annotations to the code to illustrate their use.
 
 [source,adoc]
 ----
@@ -435,7 +432,7 @@ NOTE: Annotations have been added to the code to illustrate their use.
 . Link target.
 . Numbered table title.
 
-The previous example results in the following table.
+The earlier example results in the following table.
 
 [#proposed-16bit-encodings-1]
 .proposed 16-bit encodings-1
@@ -451,11 +448,11 @@ The previous example results in the following table.
 
 === Unicode symbols
 
-For PDFs, five-digit unicode symbols generally don't work and some other unicode symbols are buggy. This failure happens because the Ruby asciidoctor-pdf toolchain makes use of Prawn to build PDFs and it's Prawn that has the problems.
+For PDFs, five-digit unicode symbols generally do not work and some other unicode symbols are buggy. This failure happens because the Ruby asciidoctor-pdf toolchain makes use of Prawn to build PDFs and it is Prawn that has the problems.
 
 Here are a few unicode examples from https://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references that might be useful:
 
-As an example, &#9830; is encoded as follows:
+As an example, encode &#9830; as follows:
 
 ```unicode
 &#9830;
@@ -510,7 +507,7 @@ sym,num,name
 
 === Mathematical notations
 
-WARNING: Asciidoctor-mathematical has some limitations. For inline expressions, the graphical representations appear small and they are centered vertically. In some cases where there is a single-character Asciidoctor-mathematical expression, it unintentionally looks like a superscript. For this reason, always use viable alternatives like _italics_ or unicode (see <<Unicode symbols>>).
+WARNING: Asciidoctor-mathematical has some limitations. For inline expressions, the graphical representations are displayed small and center vertically. In some cases where there is a single-character Asciidoctor-mathematical expression, it unintentionally is displayed as a superscript. For this reason, always use viable options such as _italics_ or unicode (see <<Unicode symbols>>).
 
 
 ==== Superscripts and subscripts
@@ -572,14 +569,14 @@ latexmath:[$C = \alpha + \beta Y^{\gamma} + \epsilon$]
 
 [TIP]
 ====
-Latexmath rendering has some limitations with respect to sizing and placement inline. This happens because of how the images for the mathematical symbols are rendered within the build process. For this reason, please avoid using single character latexmath expressions inline and preferentially make use of unicode or superscripts and subscripts when possible.
+Latexmath rendering has some limitations with respect to sizing and placement inline. This happens because of how the images for the mathematical renders symbols within the build process. For this reason, avoid using single character latexmath expressions inline and preferentially make use of unicode or superscripts and subscripts when possible.
 ====
 
 ==== Stem content
 
 The `:stem: latexmath` setting makes use of asciidoctor-mathematical for asciidoctor-pdf output.
 
-Asciidoctor Mathematical is a Ruby gem that uses native extensions. It has a few system prerequisites which limit installation to Linux and macOS. Please refer to the https://github.com/riscv/docs-templates[README in the RISC-V docs-templates repo] for information on the asciidoctor-mathematical install.
+Asciidoctor Mathematical is a Ruby gem that uses native extensions. It has a few system prerequisites that limit installation to Linux and macOS. See the https://github.com/riscv/docs-templates[README in the RISC-V docs-templates repo] for information on the asciidoctor-mathematical install.
 
 [source,adoc]
 ----
@@ -594,7 +591,7 @@ sqrt(4) = 2
 sqrt(4) = 2
 ++++
 
-In some cases, you might want to make use of unicode characters. Keep in mind that asciidoctor-pdf supports only decimal character references. See https://github.com/asciidoctor/asciidoctor-pdf/issues/486
+In some cases, you might want to make use of unicode characters. Remember that asciidoctor-pdf supports only decimal character references. See https://github.com/asciidoctor/asciidoctor-pdf/issues/486
 
 For updates to asciidoctor-pdf, see https://github.com/asciidoctor/asciidoctor-pdf.
 
@@ -621,14 +618,14 @@ Important:: Information that a user must have. For example, "After you set your
 
 IMPORTANT: example of important type
 
-Tip:: Used for Non-normative text such as clarification or hints for implementers or to convey design rationale and why other options were discontinued. RISC-V tech team is working on a solution that will allow these admonitions to be turned off.
+Tip:: Used for Non-normative text such as clarification or hints for implementers or to convey design rationale and why the team discontinued other options. RISC-V tech team is working on a solution that enables users to turn off these admonitions.
 
 TIP: example of tip type
 
 As a general rule, follow these guidelines for admonitions:
 
 * Understand that admonitions are interruptions. They should be relevant to the topic, but not necessary. If the reader skips reading it, they can still succeed.
-* If the information is necessary, make it part of the topic and even add a heading. Don't put it in an admonition.
+* If the information is necessary, make it part of the topic and even add a heading. do not put it in an admonition.
 * Limit admonitions to a maximum of 3 on a page (standard PDF page - longer HTML pages can use more.)
 * Do not include results, steps, or prerequisites in admonitions.
 * Make your admonition clear and concise.
@@ -642,7 +639,7 @@ For a single paragraph admonition, use a double colon:
 NOTE: Note content.
 ----
 
-which renders as:
+that renders as:
 
 NOTE: Note content.
 
@@ -664,14 +661,14 @@ As a general rule, follow these guidelines for admonitions:
 ====
 ----
 
-which renders as:
+that renders as:
 
 [IMPORTANT]
 ====
 As a general rule, follow these guidelines for admonitions:
 
 * Understand that admonitions are interruptions. They should be relevant to the topic, but not necessary. If the reader skips reading it, they can still succeed.
-* If the information is necessary, make it part of the topic and even add a heading. Don't put it in an admonition.
+* If the information is necessary, make it part of the topic and even add a heading. do not put it in an admonition.
 * Limit admonitions to a maximum of 3 on a page (standard PDF page - longer HTML pages can use more.)
 * Do not include results, steps, or prerequisites in admonitions.
 * Make your admonition clear and concise.
@@ -686,7 +683,7 @@ You can add a title to your admonition block.
 [WARNING]
 .Security vulnerability
 ====
-*Be aware that RLB introduces a security vulnerability if it is set after the boot process is over.* Use with caution, even when you use it temporarily. Editable PMP rules in M-mode gives a false sense of security since it only takes a few malicious instructions to lift any PMP restrictions this way. It doesn’t make sense to have a security control in place and leave it unprotected. Rule Locking Bypass is only meant as a way to optimize the allocation of PMP rules, catch errors durring debugging, and allow the bootrom/firmware to register executable _Shared-Region_ rules. If developers / vendors have no use for such functionality, they should never set ``mseccfg.RLB`` and if possible hard-wire it to 0. In any case *RLB should be disabled and locked as soon as possible*.
+*Be aware that RLB introduces a security vulnerability if you set iiiiiit after the boot process is over.* Use with caution, even when you use it temporarily. Editable PMP rules in M-mode gives a false sense of security since it only takes a few malicious instructions to lift any PMP restrictions this way. It doesn't make sense to have a security control in place and leave it unprotected. Rule Locking Bypass is only meant as a way to optimize the allocation of PMP rules, catch errors durring debugging, and allow the bootrom/firmware to register executable _Shared-Region_ rules. If developers / vendors have no use for such functionality, they should never set ``mseccfg.RLB`` and if possible hard-wire it to 0. In any case *RLB should be disabled and locked as soon as possible*.
 ====
 ----
 
@@ -695,7 +692,7 @@ Rendered:
 [WARNING]
 .Security vulnerability
 ====
-*Be aware that RLB introduces a security vulnerability if it is set after the boot process is over.* Use with caution, even when you use it temporarily. Editable PMP rules in M-mode gives a false sense of security since it only takes a few malicious instructions to lift any PMP restrictions this way. It doesn’t make sense to have a security control in place and leave it unprotected. Rule Locking Bypass is only meant as a way to optimize the allocation of PMP rules, catch errors durring debugging, and allow the bootrom/firmware to register executable _Shared-Region_ rules. If developers / vendors have no use for such functionality, they should never set ``mseccfg.RLB`` and if possible hard-wire it to 0. In any case *RLB should be disabled and locked as soon as possible*.
+*Be aware that RLB introduces a security vulnerability if you set it after the boot process is over.* Use with caution, even when you use it temporarily. Editable PMP rules in M-mode gives a false sense of security since it only takes a few malicious instructions to lift any PMP restrictions this way. It does not make sense to have a security control in place and leave it unprotected. Rule Locking Bypass is only meant as a way to optimize the allocation of PMP rules, catch errors durring debugging, and allow the bootrom/firmware to register executable _Shared-Region_ rules. If developers / vendors have no use for such functionality, they should never set ``mseccfg.RLB`` and if possible hard-wire it to 0. In any case *RLB should be disabled and locked as soon as possible*.
 ====
 
 ==== RISC-V admonition icon colors
@@ -944,4 +941,3 @@ TIP: They can contain any type of content, including admonitions like this, and
 const { expect, expectCalledWith, heredoc } = require('../test/test-utils')
 ----
 ****
-
diff --git a/src/antora-structure.adoc b/src/antora-structure.adoc
new file mode 100644
index 0000000..657086e
--- /dev/null
+++ b/src/antora-structure.adoc
@@ -0,0 +1,163 @@
+[[antora-structure]]
+== Antora repository structure
+
+RISC-V specification repositories use an https://docs.antora.org[Antora]-compatible directory structure. This enables Antora to assemble individual specification repositories into the RISC-V documentation site while also supporting a standalone PDF and HTML build using `make`.
+
+=== Repository layout
+
+A specification repository has the following top-level files and directories:
+
+----
+antora.yml                    <1>
+Makefile                      <2>
+docs-resources/               <3>
+modules/
+  ROOT/
+    nav.adoc                  <4>
+    images/                   <5>
+    pages/                    <6>
+      spec-sample.adoc
+      intro.adoc
+      chapter2.adoc
+      example.bib             <7>
+      ...
+    partials/                 <8>
+----
+<1> Antora component descriptor: identifies this repo as an Antora component and provides component metadata and configuration.
+<2> Makefile: drives the PDF/HTML build.
+<3> docs-resources: Git submodule providing shared fonts, themes, and images.
+<4> nav.adoc file: the navigation file that defines the sidebar structure for the Antora site.
+<5> Images: Symlink to `docs-resources/images` so Antora can find shared images.
+<6> Pages directory: all AsciiDoc source files live here.
+<7> Resources directory: resource files that are not asciidoc or images such as the bibliography file. Referenced by `spec-sample.adoc` via the `:bibtex-file:` attribute.
+<8> Partials directory: Optional directory for reusable AsciiDoc fragments (partials), such as Wavedrom diagram source files or content shared across chapters. Reference partials with `include::partial$filename.adoc[]`.
+
+=== antora.yml
+
+The `antora.yml` file at the repository root is the Antora https://docs.antora.org/antora/latest/component-version-descriptor/[component descriptor] and serves two purposes: it identifies the repository as an Antora content component, and it provides the component metadata and configuration (name, title, version, navigation, and AsciiDoc attributes) that Antora uses to assemble the documentation site.
+
+[source,yaml]
+----
+name: spec-sample            <1>
+title: RISC-V Example Specification (Zexmpl)  <2>
+version: ~                   <3>
+nav:
+  - modules/ROOT/nav.adoc   <4>
+----
+<1> Component name: used in Antora cross-references from other components (`xref:spec-sample:page.adoc[]`). Rename to match your specification. This attribute is used in the URL.
+<2> Human-readable title shown in the site UI. Update this for your specification.
+<3> `~` means unversioned. Set to a version string (e.g., `1.0`) when you release the specification. During development, use standard two digit versioning such as 0.1, 0.2, etc.
+<4> nav: Path to the navigation file, relative to `antora.yml`.  Using the template for non-ISA specifications, this should always be the same path, i.e. modules/ROOT/nav.adoc.
+
+When creating a new specification repository from the template, set the page-group attribute to "development" and update it to reflect specification state through the specification lifecycle. Update the `name` and `title` attributes to match your specification. For example, the Debug Specification uses:
+
+name: debug
+title: Debug Specification
+
+=== modules/ROOT/pages/
+
+All AsciiDoc source files live in `modules/ROOT/pages/`. This is the Antora convention for the default (ROOT) module's page content.
+
+The entry point for the standalone PDF and HTML build is `spec-sample.adoc`, which uses AsciiDoc `include::` directives to pull in the other chapter files. For the Antora site build, each file in `pages/` becomes a separate HTML page.
+
+When adding a new chapter:
+
+. Create the `.adoc` file in `modules/ROOT/pages/`.
+. Add an `include::` directive for it in `spec-sample.adoc` (for the PDF build).
+. Add an `xref:` entry for it in `modules/ROOT/nav.adoc` (for the Antora site build).
+
+=== modules/ROOT/nav.adoc
+
+The `nav.adoc` file defines the navigation sidebar shown in the Antora site.
+
+[source,adoc]
+----
+* xref:spec-sample.adoc[RISC-V Example Specification]
+** xref:intro.adoc[Introduction]
+** xref:chapter2.adoc[The Second Chapter]
+** xref:contributors.adoc[Contributors]
+** xref:bibliography.adoc[Bibliography]
+----
+
+Add a new entry here each time you add a chapter to `pages/`. The order of entries controls the left navigation order in the HTML version in the RISC-V Specifications Library.
+
+=== modules/ROOT/images/
+
+Antora locates images in the module directory tree.  Images used in the specification will be stored in the images directory.
+
+[[dev-playbook]]
+=== Publishing to the RISC-V documentation site
+
+A central Antora playbook maintained at https://github.com/riscv-admin/antora-dev.riscv.org[riscv-admin/antora-dev.riscv.org] assembles the RISC-V documentation site from all specification repositories. Specification authors do not manage their own playbook. Instead, they submit a pull request to that repository to register their specification as a content source.
+
+==== Naming your branch
+
+By convention, name Antora-ready branches with the version and an `-antora` suffix:
+
+----
+v1.0-antora
+v20250312-antora
+----
+
+Create this branch from your specification's release tag or working branch after the Antora directory structure is in place.
+
+==== Adding a content source
+
+In the playbook at `antora/antora-playbook.yml`, add an entry to the `content.sources` list. Use an existing entry as a model and follow the comment convention used throughout the file:
+
+[source,yaml]
+----
+# My Specification — component: my-spec | chapters 5–12
+- url: https://github.com/riscv/my-spec.git
+  branches: [v1.0-antora]
+  start_page: ROOT::index.adoc
+  start_path: /
+  worktrees: true
+  submodules: true
+----
+
+The `component` name in the comment must match the `name` field in your `antora.yml`. Set `submodules: true` if your repository uses git submodules (e.g., `docs-resources`). Set `worktrees: true` if your repository has symlinks.
+
+==== Adding numbering rules
+
+The playbook uses custom extensions to number chapters and appendixes in the site navigation. Add a corresponding entry for your specification to both the `nav_numbering_extension` and `section_numbering_extension` blocks. Both blocks share the same rules from a YAML anchor (`&numbering_rules` / `*numbering_rules`), so you only need to add a single entry in the 'nav_numbering_extension` block:
+
+[source,yaml]
+----
+# --- My Specification --------------------------------------------------
+- component: my-spec         <1>
+  module: ROOT               <2>
+  branches: ['v1.0-antora']  <3>
+  chapters: {start: 5, end: 12}  <4>
+  appendices: {start: 13, end: 14}  <5>
+----
+<1> Must match the `name` in your `antora.yml`.
+<2> Use `ROOT` for single-module specifications (the standard case).
+<3> Must match the branch name(s) listed in your `content.sources` entry.
+<4> The range of nav entries (top-level `*` items in `nav.adoc`) to number as chapters. Count from the first entry in `nav.adoc` — entries before your first chapter (e.g., a preface or overview page) are typically at position 1 through 4.
+<5> Omit this line entirely if your specification has no appendixes.
+
+==== Submitting the pull request
+
+. Fork or branch https://github.com/riscv-admin/antora-dev.riscv.org[riscv-admin/antora-dev.riscv.org].
+. Add your content source and numbering rules to `antora/antora-playbook.yml` as described above.
+. Open a pull request against the `main` branch with a brief description of the specification added.
+
+[[install-antora]]
+=== Installing Antora
+
+You need Antora to run a local site preview. It requires Node.js version 18 or later. Once you install Node.js, install Antora globally:
+
+[source,cmd]
+----
+npm install -g antora
+----
+
+Verify the installation:
+
+[source,cmd]
+----
+antora --version
+----
+
+For Node.js installation instructions, see https://nodejs.org/en/download/[nodejs.org].
diff --git a/src/authoring.adoc b/src/authoring.adoc
index 3e6b0dc..872e6d6 100644
--- a/src/authoring.adoc
+++ b/src/authoring.adoc
@@ -10,15 +10,24 @@ Asciidoctor toolchains:
 
 === RISC-V AsciiDoc authoring assets
 
-Please view the https://github.com/riscv/docs-templates[readme] in the docs-templates repo for information about the automated build processes.
+Please view the https://github.com/riscv/docs-spec-template[readme] in the docs-spec-template repo for information about the automated build processes.
 
-The docs-templates repo also contains assets, such as fonts, styles, directory structure, and themes that you need for RISC-V specifications, along with a https://github.com/riscv/docs-dev-guide/blob/main/local_build.md[document] that takes you through a local install process that supports all of the required features for a local build.
+The docs-spec-template repo contains assets such as fonts, styles, directory structure, and themes needed for RISC-V specifications. It uses an Antora-compatible directory structure with source files in `modules/ROOT/pages/`. See <<antora-structure>> for a full description of the layout.
 
-Although testing your markup by building a PDF is good practice, you can catch many common errors by simply downloading Asciidoctor and building the HTML output by using the following command:
+A https://github.com/riscv/docs-dev-guide/blob/main/local_build.md[local build guide] takes you through the local install process that supports all of the required features.
+
+Although testing your markup by building a PDF is a good practice, you can catch many common errors by downloading Asciidoctor and building the HTML output using the following command from the repository root:
+
+[source,cmd]
+----
+asciidoctor modules/ROOT/pages/spec-sample.adoc
+----
+
+Or more simply, using the Makefile:
 
 [source,cmd]
 ----
-asciidoctor book_header.adoc
+make
 ----
 
 === Writing
diff --git a/src/build-infrastructure.adoc b/src/build-infrastructure.adoc
index 9eb6cf3..8aa233f 100644
--- a/src/build-infrastructure.adoc
+++ b/src/build-infrastructure.adoc
@@ -4,6 +4,12 @@ Most RISC-V AsciiDoc documents use a `Makefile` to simplify the build process. F
 
 If Docker is already installed, the `Makefile` will invoke `docker` for the build process. Otherwise, it will build natively.
 
+=== Source directory
+
+In the Antora-based template, AsciiDoc source files live in `modules/ROOT/pages/` rather than a flat `src/` directory. The `Makefile` sets `SRC_DIR := modules/ROOT/pages` accordingly. The entry point for the PDF and HTML build is `modules/ROOT/pages/spec-sample.adoc`.
+
+For a full description of the Antora directory structure and how to register your specification with the RISC-V documentation site, see <<antora-structure>>.
+
 As an author of a document, there are some conventions to be aware of:
 
 - The version, date, and state (draft, frozen, ratified) of the document should be specified in the `.adoc` file for that document via use of the `:revnumber:` and `:revremark:` keywords. An example usage is the following:
@@ -69,3 +75,58 @@ errors. This can be adjusted by altering the `asciidoc` invocation in the `Makef
 
 This document repository currently adheres to all of these conventions, and
 may be a useful starting point for other specifications.
+
+[[spec-types]]
+=== ISA vs. non-ISA specifications
+
+How a specification is authored and where it lives depends on whether it is an ISA or non-ISA specification.
+
+ISA specifications::
+Extensions to the RISC-V Unprivileged or Privileged ISA are authored as chapters within a branch or fork of the https://github.com/riscv/riscv-isa-manual[riscv-isa-manual] repository. The specification state and revision information are set within the relevant chapter file(s) in that branch, consistent with the conventions of the ISA manual.
+
+Non-ISA specifications::
+All other RISC-V specifications are authored in their own autonomous GitHub repository, using the https://github.com/riscv/docs-spec-template[docs-spec-template] as the starting point. The repository layout, build infrastructure, and GitHub Actions workflows are all provided by the template.
+
+[[spec-lifecycle]]
+=== Specification lifecycle
+
+RISC-V specifications progress through four defined states. The current state is set via the `:revremark:` attribute in the document header and is displayed on the cover page of every build. The canonical definitions of each state are maintained at https://riscv.org/spec-state[riscv.org/spec-state].
+
+Draft::
+The specification is under active development. Everything is subject to change. Use `:revremark: This document is in the link:http://riscv.org/spec-state[Development state]` or simply `:revremark: Draft`.
+
+Stable::
+The specification is feature-complete but may still change in response to public review feedback. Use `:revremark: Stable`.
+
+Frozen::
+The specification has completed public review. Only critical bug fixes are permitted. Implementations based on this version may proceed at the implementer's risk. Use `:revremark: Frozen`.
+
+Ratified::
+The specification has been formally ratified by RISC-V International. No further changes will be made to this version. Use `:revremark: Ratified`.
+
+==== State advancement is manual
+
+State advancement is *not* automated. No process or workflow automatically promotes a specification from one state to the next. Authors must update `:revremark:` in the source document by hand, following approval through the appropriate RISC-V governance process.
+
+==== Non-ISA specifications: releasing a new state
+
+For non-ISA specifications, each state transition should be accompanied by a corresponding GitHub release so the published PDF is permanently associated with that state. The `build-pdf.yml` GitHub Actions workflow supports this via a manual `workflow_dispatch` trigger.
+
+To publish a release at a new state:
+
+. Update `:revremark:` in `modules/ROOT/pages/spec-sample.adoc` to the new state.
+. Update `:revnumber:` to the appropriate version string.
+. Commit and push the changes.
+. In GitHub, navigate to *Actions → Create Specification Document → Run workflow*.
+. Select the matching `revision_mark` (Draft, Stable, Frozen, or Ratified).
+. Set `prerelease` and `draft` flags as appropriate.
+. Run the workflow — it will build the PDF, create a git tag, and publish a GitHub release.
+
+[NOTE]
+====
+The `revision_mark` selected in the workflow dispatch sets the `REVMARK` environment variable passed to `make`, which overrides `:revremark:` in the built PDF. Ensure the value you select matches what is set in the source document so the two are consistent.
+====
+
+==== ISA specifications: state within the ISA manual
+
+For ISA specifications, the specification state is not tracked via a standalone GitHub release workflow. Instead, the state is reflected within the chapter(s) of the relevant ISA manual — either the Unprivileged or Privileged specification — in the branch of https://github.com/riscv/riscv-isa-manual[riscv-isa-manual] where the author is working. The state and revision information should follow the conventions established within that repository and be consistent with the overall state of the ISA manual branch.
diff --git a/src/docs-dev-guide.adoc b/src/docs-dev-guide.adoc
index 3e5238e..0b787a4 100755
--- a/src/docs-dev-guide.adoc
+++ b/src/docs-dev-guide.adoc
@@ -74,6 +74,8 @@ include::intro.adoc[]
 
 include::authoring.adoc[]
 
+include::antora-structure.adoc[]
+
 include::a_few_basics.adoc[]
 
 include::index_bib.adoc[]
diff --git a/src/intro.adoc b/src/intro.adoc
index d9c1255..ebcd357 100644
--- a/src/intro.adoc
+++ b/src/intro.adoc
@@ -17,3 +17,20 @@ RISC-V documentation contributors:
 
 - Create a Linux foundation ID with https://lfx.linuxfoundation.org/[LFX].
 - Become a https://riscv.org/membership/[member of the RISC-V International] organization.
+
+[[getting-help]]
+=== Getting help
+
+If you have questions about authoring, the build toolchain, or the Antora documentation site, the following resources are available:
+
+https://lists.riscv.org/g/sig-documentation[sig-documentation mailing list]::
+The primary venue for discussion about RISC-V documentation tooling, processes, and the Antora site. Post here for questions about the build infrastructure, the dev playbook, or contributing a new specification.
+
+mailto:help@riscv.org[help@riscv.org]::
+General RISC-V support address for questions that don't fit the mailing list.
+
+https://github.com/riscv/docs-dev-guide/issues[docs-dev-guide GitHub issues]::
+File an issue here if you find something incorrect or missing in this guide.
+
+https://github.com/riscv-admin/antora-dev.riscv.org/issues[antora-dev.riscv.org GitHub issues]::
+File an issue here for problems with the RISC-V Antora documentation site or the dev playbook.