spec-up-t 1.6.11 → 1.6.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-up-t",
-  "version": "1.6.11",
+  "version": "1.6.13",
   "description": "Technical specification drafting tool that generates rich specification documents from markdown. Forked from https://github.com/decentralized-identity/spec-up by Daniel Buchner (https://github.com/csuwildcat)",
   "main": "./index",
   "repository": {

package/src/freeze-spec-data.js

@@ -16,7 +16,11 @@ const config = fs.readJsonSync('specs.json');
 const outputPath = config.specs[0].output_path;
 
 const sourceFile = path.join(outputPath, 'index.html');
-const destDir = path.join(outputPath, 'versions');
+
+// spec-versions/ lives at the repo root and is committed to the main branch.
+// This is the source of truth — it survives gh-pages resets and fresh CI checkouts.
+// docs/versions/ is the derived, deployed copy and is always rebuilt from here.
+const destDir = 'spec-versions';
 
 // A snapshot can only be created when the specification has been built at least once.
 // If index.html is missing, the user must run `npm run menu 1` (or `npm run menu 4`) first.
@@ -117,7 +121,11 @@ async function run() {
 
     Logger.success(`Created a freezed specification version in ${destFile}`);
 
-    // Update the versions index.html to include the newly created version
+    // Sync spec-versions/ → docs/versions/ so the local preview reflects the
+    // new snapshot immediately, then regenerate the versions index page.
+    const syncSpecVersions = require('./pipeline/configuration/sync-spec-versions.js');
+    syncSpecVersions(outputPath);
+
     const createVersionsIndex = require('./pipeline/configuration/create-versions-index.js');
     createVersionsIndex(outputPath);
 }

package/src/install-from-boilerplate/boilerplate/.github/workflows/menu.yml

@@ -85,8 +85,13 @@ jobs:
               npm run todocx
               ;;
             freeze)
-              # Pass the label to freeze-spec-data.js via environment variable.
-              # If freeze_label is empty the script falls back to the auto-generated default.
+              # A fresh CI checkout has no docs/ (gitignored), so we must render
+              # first to give freeze-spec-data.js the docs/index.html it needs.
+              # freeze-spec-data.js then writes the snapshot to spec-versions/,
+              # which is tracked in git. The commit+push step below commits
+              # spec-versions/ to the main branch, which triggers
+              # render-and-deploy.yml to deploy the full spec (including versions).
+              npm run collectExternalReferences
               FREEZE_LABEL="${{ github.event.inputs.freeze_label }}" npm run freeze
               ;;
             custom-update)
@@ -126,6 +131,8 @@ jobs:
               git commit -m "Collect external references" || echo "No changes to commit"
               ;;
             freeze)
+              # spec-versions/ is tracked in git — committing it triggers
+              # render-and-deploy.yml, which deploys the full spec with versions.
               git commit -m "Freeze specification" || echo "No changes to commit"
               ;;
             custom-update)

package/src/install-from-boilerplate/boilerplate/.github/workflows/render-and-deploy.yml

@@ -61,9 +61,27 @@ jobs:
 
       # Collect external references — this also renders the specification and
       # writes output to the path defined in specs.json (output_path, typically ./docs/).
+      # The render pipeline (prepare-spec-configuration.js) automatically copies
+      # spec-versions/ → docs/versions/ so frozen snapshots are always included.
       - name: Collect external references and render
         run: npm run collectExternalReferences
 
+      # Preserve the CNAME file from gh-pages before deploying.
+      # peaceiris/actions-gh-pages replaces the entire gh-pages branch with the
+      # contents of ./docs. A fresh CI checkout of main never contains docs/CNAME
+      # (docs/ is gitignored), so without this step any previously committed CNAME
+      # would be silently deleted on every render.
+      - name: Preserve CNAME from gh-pages
+        run: |
+          git fetch origin gh-pages 2>/dev/null || true
+          CNAME_CONTENT=$(git show origin/gh-pages:CNAME 2>/dev/null || echo "")
+          if [ -n "$CNAME_CONTENT" ]; then
+            echo "$CNAME_CONTENT" > docs/CNAME
+            echo "CNAME preserved: $CNAME_CONTENT"
+          else
+            echo "No CNAME found on gh-pages — nothing to preserve"
+          fi
+
       # Push the rendered ./docs output to the gh-pages branch.
       # peaceiris/actions-gh-pages creates the branch on first run when it
       # does not yet exist — no manual branch setup is required.

package/src/install-from-boilerplate/boilerplate-templates/boilerplate-template-01/spec/spec-body.md

@@ -0,0 +1,52 @@
+## Requirements
+
+*This section contains the normative requirements of the specification. Replace the examples below with your actual requirements.*
+
+### General Requirements
+
+The following requirements apply to all conforming implementations:
+
+1. Implementations MUST ...
+2. Implementations SHOULD ...
+3. Implementations MAY ...
+
+### Protocol Requirements
+
+*Add detailed technical or protocol requirements here.*
+
+::: note Informative Note
+  Requirements marked with MUST are normative. Requirements marked with SHOULD are recommended but not mandatory. Requirements marked with MAY are optional.
+:::
+
+::: todo Open Issue
+  Placeholder — replace with actual open items or remove this block before publication.
+:::
+
+## Architecture Overview
+
+*Provide an architectural description of the system or protocol defined by this specification. Diagrams and tables are encouraged.*
+
+### The ToIP Stack Context
+
+This specification operates within the [ToIP Technology Architecture Specification](https://trustoverip.github.io/TechArch/) layered model. The ToIP stack comprises four layers:
+
+| Layer | Name | Description |
+|------:|:-----|:------------|
+| 4 | Application Ecosystem | Trust applications and governance frameworks |
+| 3 | Trust Task | Credential exchange and trust negotiation |
+| 2 | Trust Spanning | Peer-to-peer messaging between agents |
+| 1 | Trust Support | Verifiable data registries and DID infrastructure |
+
+*Indicate which layer(s) this specification addresses.*
+
+## Security Considerations
+
+*Describe relevant security properties, threat models, and mitigations.*
+
+::: warning Security Note
+  Implementers MUST carefully review the security considerations before deployment.
+:::
+
+## Privacy Considerations
+
+*Describe how privacy is preserved and any data-minimization requirements.*

package/src/install-from-boilerplate/boilerplate-templates/boilerplate-template-01/spec/spec-coda.md

@@ -0,0 +1,25 @@
+## Appendix
+
+### Revision History
+
+| Version | Date | Changes |
+|--------:|:-----|:--------|
+| 0.1 | [Date] | Initial draft |
+
+### References
+
+#### Normative References
+
+- ToIP Technical Architecture Specification — [https://trustoverip.github.io/TechArch/](https://trustoverip.github.io/TechArch/)
+- W3C Verifiable Credentials Data Model — [https://www.w3.org/TR/vc-data-model/](https://www.w3.org/TR/vc-data-model/)
+- W3C Decentralized Identifiers (DIDs) — [https://www.w3.org/TR/did-core/](https://www.w3.org/TR/did-core/)
+
+#### Informative References
+
+- Trust over IP Foundation — [https://trustoverip.org/](https://trustoverip.org/)
+- ToIP Technical Architecture — [https://trustoverip.org/our-work/technical-architecture/](https://trustoverip.org/our-work/technical-architecture/)
+- Spec-Up-T Documentation — [https://trustoverip.github.io/spec-up-t-website/](https://trustoverip.github.io/spec-up-t-website/)
+
+### Acknowledgements
+
+This specification was developed with contributions from members of the [Trust over IP Foundation](https://trustoverip.org/) and reviewed by the ToIP Steering Committee.

package/src/install-from-boilerplate/boilerplate-templates/boilerplate-template-01/spec/spec-head.md

@@ -0,0 +1,33 @@
+# [Your Specification Title]
+
+::: warning Warning Notice
+  This content is created with Artificial Intelligence, based on information about ToIP available online.
+:::
+
+## Introduction
+
+*This is a template for [Trust over IP (ToIP)](https://trustoverip.org/) specifications. Replace all placeholder text with your own content. See the [Spec-Up-T documentation](https://trustoverip.github.io/spec-up-t-website/) for authoring guidance.*
+
+This specification is developed under the auspices of the [Trust over IP Foundation](https://trustoverip.org/) and follows the structure recommended by the ToIP Steering Committee.
+
+## Abstract
+
+*Provide a brief abstract summarizing the purpose, scope, and intended audience of this specification. One to three paragraphs is typical.*
+
+## Scope
+
+This document defines the normative requirements for ...
+
+The following topics are **within scope**:
+
+- ...
+
+The following topics are **out of scope**:
+
+- ...
+
+## Conformance
+
+As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
+
+The key words *MAY*, *MUST*, *MUST NOT*, *OPTIONAL*, *RECOMMENDED*, *REQUIRED*, *SHOULD*, and *SHOULD NOT* in this document are to be interpreted as described in [BCP 14](https://www.rfc-editor.org/info/bcp14) when, and only when, they appear in all capitals, as shown here.

package/src/install-from-boilerplate/boilerplate-templates/boilerplate-template-01/spec/terms-and-definitions-intro.md

@@ -0,0 +1,5 @@
+[//]: # (This file, named "terms-and-definitions-intro.md" is mandatory and should not be deleted. However, you can safely delete this comment and replace it with text of your choice.)
+
+## Terms and definitions
+
+This section defines key terms used throughout this specification. Terms marked with cross-references (xref) or term-references (tref) link to definitions in other ToIP specifications.

package/src/install-from-boilerplate/boilerplate-templates/boilerplate-template-01/spec/terms-definitions/access-control.md

@@ -0,0 +1,5 @@
+[[tref: toipglos, access-control]]
+
+~ *Note: This is a **tref** example — the definition of "access-control" is imported from the ToIP Glossary rather than defined locally. Use `tref` when you want to reuse the exact definition from another specification. Replace `toipglos` with the external spec key configured in your `specs.json`.*
+
+~ See also: [[ref: trust registry]], [[xref: toipglos, controller]].

package/src/install-from-boilerplate/boilerplate-templates/boilerplate-template-01/spec/terms-definitions/decentralized-identifier.md

@@ -0,0 +1,7 @@
+[[def: decentralized identifier, decentralized identifiers, DID, DIDs]]
+
+~ A **decentralized identifier** (DID) is a globally unique, persistent identifier that does not require a centralized registration authority. A DID resolves to a DID document containing cryptographic material that allows the [[ref: controller]] to authenticate and prove control.
+
+~ *Note: This is an example term included for demonstration purposes. Replace this definition with precise, normative language appropriate to your specification.*
+
+~ See also: [[ref: verifiable credential]], [[xref: toipglos, controller]].

package/src/install-from-boilerplate/boilerplate-templates/boilerplate-template-01/spec/terms-definitions/trust-registry.md

@@ -0,0 +1,7 @@
+[[def: trust registry, trust registries]]
+
+~ A **trust registry** is an authoritative source that an ecosystem uses to determine whether a party (such as an [[ref: issuer]] or [[ref: verifier]]) is trusted within the constraints of a given [[ref: governance framework]]. It enables automated trust decisions without relying on out-of-band verification.
+
+~ *Note: This is an example term included for demonstration purposes. Replace this definition with precise, normative language appropriate to your specification.*
+
+~ See also: [[ref: governance framework]], [[xref: toipglos, issuer]].

package/src/install-from-boilerplate/boilerplate-templates/boilerplate-template-01/spec/terms-definitions/verifiable-credential.md

@@ -0,0 +1,7 @@
+[[def: verifiable credential, verifiable credentials, VC, VCs]]
+
+~ A **verifiable credential** (VC) is a tamper-evident digital credential whose authorship can be cryptographically verified. It contains claims made by an [[ref: issuer]] about a [[ref: holder]], and is presented to a [[ref: verifier]] as proof.
+
+~ *Note: This is an example term included for demonstration purposes. Replace this definition with precise, normative language appropriate to your specification.*
+
+~ See also: [[xref: toipglos, issuer]], [[xref: toipglos, holder]] for how these roles are defined in the ToIP Glossary.

package/src/install-from-boilerplate/boilerplate-templates/boilerplate-template-01/specs.json

@@ -0,0 +1,35 @@
+{
+    "specs": [
+        {
+            "title": "[Your Specification Title]",
+            "description": "A Trust over IP Foundation specification. Replace this description with a summary of your specification.",
+            "author": "Trust over IP Foundation",
+            "spec_directory": "./spec",
+            "spec_terms_directory": "terms-definitions",
+            "output_path": "./docs",
+            "markdown_paths": [
+                "spec-head.md",
+                "terms-and-definitions-intro.md",
+                "spec-body.md",
+                "spec-coda.md"
+            ],
+            "logo": "https://raw.githubusercontent.com/trustoverip/spec-up-t/refs/heads/master/src/install-from-boilerplate/boilerplate/static/logo.svg",
+            "logo_link": "https://github.com/trustoverip/spec-up-t",
+            "favicon": "https://raw.githubusercontent.com/trustoverip/spec-up-t/refs/heads/master/src/install-from-boilerplate/boilerplate/static/favicon.ico",
+            "source": {
+                "host": "github",
+                "account": "trustoverip",
+                "repo": "your-spec-repo"
+            },
+            "external_specs": [
+                {
+                    "external_spec": "toipglos",
+                    "gh_page": "https://glossary.trustoverip.org/",
+                    "url": "https://github.com/trustoverip/ctwg-main-glossary"
+                }
+            ],
+            "katex": false,
+            "anchor_symbol": "§"
+        }
+    ]
+}

package/src/install-from-boilerplate/boilerplate-templates/boilerplate-template-02/spec/spec-part-1.md

@@ -0,0 +1,17 @@
+# Spec-Up-T Specification
+
+## Part 1: Introduction and Background
+
+### About This Specification
+
+This is a default Spec-Up-T installation using the "Multi-Part" content template. Find information on the [Spec-Up-T documentation website](https://trustoverip.github.io/spec-up-t-website/).
+
+This is a demo site for Spec-Up-T. The subject matter – gardening and related terms – is used purely as an example to demonstrate how the system works. You can replace these demo terms and definitions with your own content to suit your documentation needs.
+
+### Background
+
+Provide background information and context for your specification here. Explain the problem space, motivation, and any relevant history that helps readers understand the purpose of this document.
+
+### Scope and Purpose
+
+Define the boundaries of what this specification covers and what it does not. Clearly stating the scope helps readers understand the applicability of the specification.

package/src/install-from-boilerplate/boilerplate-templates/boilerplate-template-02/spec/spec-part-2.md

@@ -0,0 +1,65 @@
+## Part 2: Technical Details
+
+This section contains the core technical content of the specification. Add your detailed requirements, algorithms, data formats, and protocols here.
+
+### Blockquote
+
+> To be, or not to be, that is the question:
+Whether 'tis nobler in the mind to suffer
+The slings and arrows of outrageous fortune,
+Or to take arms against a sea of troubles
+And by opposing end them. To die—to sleep,
+No more;
+
+### Notices
+
+::: note Basic Note
+  Check this out.
+:::
+
+::: warning Warning Notice
+  Houston, I think we have a problem
+:::
+
+::: todo Really Important
+  Get this done!
+:::
+
+::: example Code Example
+
+```json
+// Some comment in JSON
+{
+  "foo": "bar",
+  "baz": 2
+}
+```
+
+:::
+
+### Content from External Files
+
+Use the following format to pull in content from other files in your project:
+
+This text has been inserted here from another file: [[insert: assets/test.text]]
+
+::: example Code Example
+
+```json
+[[insert: assets/test.json]]
+```
+
+:::
+
+### Tables
+
+|              Stage | Direct Products | ATP Yields |
+| -----------------: | --------------: | ---------: |
+|         Glycolysis |           2 ATP |            |
+|                 ^^ |          2 NADH |   3--5 ATP |
+| Pyruvaye oxidation |          2 NADH |      5 ATP |
+|  Citric acid cycle |           2 ATP |            |
+|                 ^^ |          6 NADH |     15 ATP |
+|                 ^^ |         2 FADH2 |      3 ATP |
+|     **30--32** ATP |                 |            |
+[Net ATP yields per hexose]

package/src/install-from-boilerplate/boilerplate-templates/boilerplate-template-02/spec/spec-part-3.md

@@ -0,0 +1,17 @@
+## Part 3: Summary and Implementation Notes
+
+### Summary
+
+Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo. Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt. Neque porro quisquam est, qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit, sed quia non numquam eius modi tempora incidunt ut labore et dolore magnam aliquam quaerat voluptatem. Ut enim ad minima veniam, quis nostrum exercitationem ullam corporis suscipit laboriosam, nisi ut aliquid ex ea commodi consequatur? Quis autem vel eum iure reprehenderit qui in ea voluptate velit esse quam nihil molestiae consequatur, vel illum qui dolorem eum fugiat quo voluptas nulla pariatur?
+
+### Implementation Notes
+
+Include implementation guidance, best practices, and notes for implementers here. This section helps bridge the gap between the specification and practical implementation.
+
+### Future Work
+
+Describe planned extensions, improvements, or areas for further development here.
+
+### References
+
+This section can contain references to other documents, standards, and resources used in this specification.

package/src/install-from-boilerplate/boilerplate-templates/boilerplate-template-02/spec/terms-and-definitions-intro.md

@@ -0,0 +1,5 @@
+[//]: # (This file, named "terms-and-definitions-intro.md" is mandatory and should not be deleted. However, you can safely delete this comment and replace it with text of your choice.)
+
+## Terms and definitions
+
+This is the terms and definitions section

package/src/install-from-boilerplate/boilerplate-templates/boilerplate-template-02/spec/terms-definitions/composability.md

@@ -0,0 +1,5 @@
+[[tref: ExtRef1, greenhouse]]
+
+~ Note: This is a tref example. The term "greenhouse" is imported from the ExtRef1 external glossary (focused on greenhouse and irrigation concepts).
+
+~ See also: [[xref: ExtRef2, propagation]] for plant propagation from ExtRef2.

package/src/install-from-boilerplate/boilerplate-templates/boilerplate-template-02/spec/terms-definitions/compost.md

@@ -0,0 +1,3 @@
+[[def: compost, composting, Compost]]
+
+~ Compost is a mixture of decayed organic matter used to fertilize soil. It is created through the process of composting, where materials like leaves, food scraps, and grass clippings break down over time. Compost improves soil structure and provides nutrients for plants. See also [[ref: Mulch]], [[ref: Soil]], [[ref: Fertilizer]], [[ref: Seedling]], [[ref: Watering]].

package/src/install-from-boilerplate/boilerplate-templates/boilerplate-template-02/spec/terms-definitions/dormancy.md

@@ -0,0 +1,5 @@
+[[tref: ExtRef2, dormancy]]
+
+~ Note: This is a tref example. The term "dormancy" is imported from the ExtRef2 external glossary (focused on plant lifecycle and propagation concepts).
+
+~ See also: [[xref: ExtRef1, perennial]] for perennial plants from ExtRef1.

package/src/install-from-boilerplate/boilerplate-templates/boilerplate-template-02/spec/terms-definitions/fertilizer.md

@@ -0,0 +1,3 @@
+[[def: fertilizer, fertilizing, Fertilizer]]
+
+~ Fertilizer is a substance added to soil or plants to supply essential nutrients and promote growth. Fertilizers can be organic, like compost, or synthetic. Proper fertilizing ensures healthy plant development. See also [[ref: Compost]], [[ref: Mulch]], [[ref: Soil]], [[ref: Watering]], [[ref: Seedling]].

package/src/install-from-boilerplate/boilerplate-templates/boilerplate-template-02/spec/terms-definitions/greenhouse.md

@@ -0,0 +1,5 @@
+[[tref: ExtRef1, greenhouse]]
+
+~ Note: This is a tref example. The term "greenhouse" is imported from the ExtRef1 external glossary (focused on greenhouse and irrigation concepts).
+
+~ See also: [[xref: ExtRef2, propagation]] for plant propagation from ExtRef2.

package/src/install-from-boilerplate/boilerplate-templates/boilerplate-template-02/spec/terms-definitions/mulch.md

@@ -0,0 +1,3 @@
+[[def: mulch, mulching, Mulch]]
+
+~ Mulch is a layer of material, such as wood chips or straw, spread on the surface of soil to retain moisture, suppress weeds, and regulate temperature. Mulching helps improve plant health and soil quality. Related terms: [[ref: Compost]], [[ref: Soil]], [[ref: Fertilizer]].

package/src/install-from-boilerplate/boilerplate-templates/boilerplate-template-02/spec/terms-definitions/pruning.md

@@ -0,0 +1,3 @@
+[[def: pruning, Pruning]]
+
+~ Pruning is the practice of trimming plants by cutting away dead or overgrown branches or stems. Pruning encourages healthy growth and improves the shape of plants. See also [[ref: Seedling]], [[ref: Watering]].

package/src/install-from-boilerplate/boilerplate-templates/boilerplate-template-02/spec/terms-definitions/seedling.md

@@ -0,0 +1,3 @@
+[[def: seedling, seedlings, Seedling]]
+
+~ A seedling is a young plant that has recently sprouted from a seed. Seedlings are delicate and require proper soil, water, and light to grow into mature plants. See also [[ref: Soil]], [[ref: Compost]], [[ref: Watering]].

package/src/install-from-boilerplate/boilerplate-templates/boilerplate-template-02/spec/terms-definitions/soil.md

@@ -0,0 +1,13 @@
+[[def: soil, soils, Soil]]
+
+~ Soil is the upper layer of earth in which plants grow. It consists of a mixture of organic matter, minerals, gases, liquids, and organisms that together support life. Healthy soil is essential for gardening and agriculture.
+
+~ Refs examples: [[ref: Compost]], [[ref: Mulch]], [[ref: Fertilizer]].
+
+~ Xref examples from external gardening glossaries: 
+~ - From ExtRef1 (greenhouse focus): [[xref: ExtRef1, greenhouse]], [[xref: ExtRef1, irrigation]]
+~ - From ExtRef2 (lifecycle focus): [[xref: ExtRef2, dormancy]], [[xref: ExtRef2, propagation]]
+
+~ Note: The term "soil" exists in ExtRef1 and ExtRef2 with different definitions focused on their respective themes.
+
+~ Soil quality affects water retention, nutrient availability, and plant health. Amending soil with compost or mulch can improve its structure and fertility. Fertilizer may be added to supplement nutrients as needed.

package/src/install-from-boilerplate/boilerplate-templates/boilerplate-template-02/spec/terms-definitions/watering.md

@@ -0,0 +1,3 @@
+[[def: watering, Watering]]
+
+~ Watering is the act of supplying water to plants to help them grow. Proper watering is essential for healthy roots and overall plant development. Overwatering or underwatering can harm plants. See also [[ref: Soil]], [[ref: Seedling]], [[ref: Mulch]].

package/src/install-from-boilerplate/boilerplate-templates/boilerplate-template-02/specs.json

@@ -0,0 +1,40 @@
+{
+    "specs": [
+        {
+            "title": "Spec-Up-T Starterpack",
+            "description": "Create technical specifications in markdown. Based on the original Spec-Up, extended with Terminology tooling",
+            "author": "Trust over IP Foundation",
+            "spec_directory": "./spec",
+            "spec_terms_directory": "terms-definitions",
+            "output_path": "./docs",
+            "markdown_paths": [
+                "spec-part-1.md",
+                "terms-and-definitions-intro.md",
+                "spec-part-2.md",
+                "spec-part-3.md"
+            ],
+            "logo": "https://raw.githubusercontent.com/trustoverip/spec-up-t/refs/heads/master/src/install-from-boilerplate/boilerplate/static/logo.svg",
+            "logo_link": "https://github.com/trustoverip/spec-up-t",
+            "favicon": "https://raw.githubusercontent.com/trustoverip/spec-up-t/refs/heads/master/src/install-from-boilerplate/boilerplate/static/favicon.ico",
+            "source": {
+                "host": "github",
+                "account": "trustoverip",
+                "repo": "spec-up-t-starter-pack"
+            },
+            "external_specs": [
+                {
+                    "external_spec": "ExtRef1",
+                    "gh_page": "https://trustoverip.github.io/spec-up-t-demo-external-ref-1/",
+                    "url": "https://github.com/trustoverip/spec-up-t-demo-external-ref-1"
+                },
+                {
+                    "external_spec": "ExtRef2",
+                    "gh_page": "https://trustoverip.github.io/spec-up-t-demo-external-ref-2/",
+                    "url": "https://github.com/trustoverip/spec-up-t-demo-external-ref-2"
+                }
+            ],
+            "katex": false,
+            "anchor_symbol": "§"
+        }
+    ]
+}

package/src/install-from-boilerplate/config-templates.js

@@ -0,0 +1,39 @@
+/**
+ * Configuration for available content templates.
+ *
+ * Each template provides a different structure for specification markdown files.
+ * The assets/ and static/ directories remain the same across all templates
+ * and are always sourced from the original boilerplate.
+ *
+ * - id: unique identifier used in env var SPEC_UP_T_TEMPLATE and GitHubUi
+ * - name: human-readable name shown during selection
+ * - description: brief explanation of the template structure
+ * - directory: folder name inside boilerplate-templates/, or null for default
+ */
+
+
+/**
+ * IMPORTANT: When adding new templates, also update the template selection logic in the GitHubUi file `CreateSpecUpProject.vue`.
+ */
+const templates = [
+    {
+        id: 'default',
+        name: 'Default (Starter Pack)',
+        description: 'Standard boilerplate with head, body, and example markup files',
+        directory: null
+    },
+    {
+        id: 'boilerplate-template-01',
+        name: 'Trust over IP Specification (Intro, Body, Coda)',
+        description: 'Structured with introduction, body, and concluding sections',
+        directory: 'boilerplate-template-01'
+    },
+    {
+        id: 'boilerplate-template-02',
+        name: 'Multi-Part Specification (Part 1, 2, 3)',
+        description: 'Organized in sequential parts for longer specifications',
+        directory: 'boilerplate-template-02'
+    }
+];
+
+module.exports = { templates };

package/src/install-from-boilerplate/copy-boilerplate.js

@@ -1,23 +1,76 @@
 const fs = require('fs-extra');
-const path = require('path');
+const path = require('node:path');
 const Logger = require('../utils/logger');
 
-function copyBoilerplate() {
+/**
+ * Copies the boilerplate files to the consuming project root.
+ * If a template is specified (non-default), the template's spec/ directory
+ * and specs.json overwrite those from the default boilerplate.
+ * The assets/ and static/ directories always come from the original boilerplate.
+ *
+ * @param {Object|null} template - Template object from config-templates.js, or null/undefined for default.
+ */
+function copyBoilerplate(template) {
     const sourceDir = path.join(__dirname, './', 'boilerplate');
+    // // Use process.cwd() so the destination is always the consuming project root,
+    // // regardless of whether spec-up-t is installed from npm or via `npm link`.
+    // // I am not sure if this works in all cases. Needs testing.
+    // const projectRoot = process.cwd();
+
+    const projectRoot = path.join(__dirname, '../../../../');
+
+    // Step 1: Copy everything from the default boilerplate
     const items = fs.readdirSync(sourceDir);
-    items.forEach(item => {
+    for (const item of items) {
         const srcPath = path.join(sourceDir, item);
-        // Root of the project
-        const destPath = path.join(__dirname, '../../../../', item);
+        const destPath = path.join(projectRoot, item);
         fs.cpSync(srcPath, destPath, { recursive: true });
-    });
+    }
 
     // Rename the copied gitignore file to .gitignore
-    const gitignorePath = path.join(__dirname, '../../../../', 'gitignore');
-    const gitignoreDestPath = path.join(__dirname, '../../../../', '.gitignore');
+    const gitignorePath = path.join(projectRoot, 'gitignore');
+    const gitignoreDestPath = path.join(projectRoot, '.gitignore');
     fs.renameSync(gitignorePath, gitignoreDestPath);
 
     Logger.success('Copied spec-up-t-boilerplate to current directory');
+
+    // Step 2: If a non-default template was selected, overlay template-specific files
+    if (template?.directory) {
+        applyTemplate(template, projectRoot);
+    }
+}
+
+/**
+ * Overlays template-specific spec/ and specs.json onto the project root,
+ * replacing the default boilerplate versions.
+ *
+ * @param {Object} template - Template object with a directory property.
+ * @param {string} projectRoot - Absolute path to the consuming project root.
+ */
+function applyTemplate(template, projectRoot) {
+    const templateDir = path.join(__dirname, 'boilerplate-templates', template.directory);
+
+    if (!fs.existsSync(templateDir)) {
+        Logger.error(`Template directory not found: ${template.directory}`);
+        return;
+    }
+
+    // Replace spec/ directory with the template's version
+    const destSpecDir = path.join(projectRoot, 'spec');
+    const templateSpecDir = path.join(templateDir, 'spec');
+
+    if (fs.existsSync(templateSpecDir)) {
+        fs.rmSync(destSpecDir, { recursive: true, force: true });
+        fs.cpSync(templateSpecDir, destSpecDir, { recursive: true });
+        Logger.success(`Applied template spec/ from: ${template.name}`);
+    }
+
+    // Replace specs.json with the template's version
+    const templateSpecsJson = path.join(templateDir, 'specs.json');
+    if (fs.existsSync(templateSpecsJson)) {
+        fs.cpSync(templateSpecsJson, path.join(projectRoot, 'specs.json'));
+        Logger.success(`Applied template specs.json from: ${template.name}`);
+    }
 }
 
 module.exports = copyBoilerplate;

package/src/install-from-boilerplate/copy-system-files.js

@@ -14,9 +14,15 @@ function copySystemFiles() {
     systemFiles.forEach(item => {
         const srcPath = path.join(sourceDir, item);
 
+        // // Use process.cwd() so the destination is always the consuming project root,
+        // // regardless of whether spec-up-t is installed from npm or via `npm link`.
+        // // I am not sure if this works in all cases. Needs testing.
+        // const destPath = path.join(process.cwd(), item);
+
         // Root of the project
         const destPath = path.join(__dirname, '../../../../', item);
 
+
         try {
             fs.cpSync(srcPath, destPath, { recursive: true });
             Logger.success(`Copied ${item} to ${destPath}`);

package/src/install-from-boilerplate/custom-update.js

@@ -1,3 +1,4 @@
+const fs = require('fs-extra');
 const { configScriptsKeys } = require('./config-scripts-keys');
 const { configOverwriteScriptsKeys } = require('./config-scripts-keys');
 const addScriptsKeys = require('./add-scripts-keys');
@@ -5,6 +6,7 @@ const copySystemFiles = require('./copy-system-files');
 const { gitIgnoreEntries } = require('./config-gitignore-entries');
 const { updateGitignore } = require('./add-gitignore-entries');
 const updateDependencies = require('./update-dependencies');
+const migrateVersionsToSpecVersions = require('./migrate-versions-to-spec-versions');
 const Logger = require('../utils/logger');
 
 
@@ -17,8 +19,18 @@ const customUpdate = () => {
     // Update dependencies based on package.spec-up-t.json
     updateDependencies();
 
-    // Custom logic here
-    // ...
+    // One-time migration: repos that stored snapshots in docs/versions/ (the old
+    // "commit docs/" regime) need their snapshots moved to spec-versions/ so they
+    // survive after docs/ is removed from git tracking. Safe to run on every
+    // custom-update — already-migrated versions are not overwritten.
+    try {
+        const config = fs.readJsonSync('specs.json');
+        const outputPath = config.specs[0].output_path;
+        migrateVersionsToSpecVersions(outputPath);
+    } catch (error) {
+        // specs.json missing or malformed — skip migration silently.
+        Logger.info('Skipping versions migration: could not read specs.json');
+    }
 }
 
 // Call custom update

package/src/install-from-boilerplate/install.js

@@ -1,8 +1,18 @@
 const copyBoilerplate = require('./copy-boilerplate');
 const { configScriptsKeys } = require('./config-scripts-keys');
 const addScriptsKeys = require('./add-scripts-keys');
+const { templates } = require('./config-templates');
 
-copyBoilerplate();
+// Resolve template from SPEC_UP_T_TEMPLATE environment variable.
+// If not set or set to 'default', uses the original boilerplate (backward compatible).
+const envTemplateId = process.env.SPEC_UP_T_TEMPLATE;
+let selectedTemplate = null;
+
+if (envTemplateId && envTemplateId !== 'default') {
+    selectedTemplate = templates.find(t => t.id === envTemplateId) || null;
+}
+
+copyBoilerplate(selectedTemplate);
 addScriptsKeys(configScriptsKeys);
 
 require('./postinstall-message');

package/src/install-from-boilerplate/migrate-versions-to-spec-versions.js

@@ -0,0 +1,85 @@
+/**
+ * @file migrate-versions-to-spec-versions.js
+ * @description One-time migration helper for repositories that were created under the
+ * old "commit docs/" regime. Those repos store frozen snapshots inside docs/versions/.
+ *
+ * Starting with the issue270 changes, snapshots are stored in spec-versions/ (tracked,
+ * at the repo root) instead of docs/versions/ (gitignored, ephemeral). This migration
+ * copies any snapshots found in docs/versions/ into spec-versions/ so they are not
+ * lost when the user eventually removes docs/ from git tracking.
+ *
+ * - Safe to run more than once: already-migrated versions are not overwritten.
+ * - Does nothing when docs/versions/ does not exist (new repos or repos that never froze).
+ * - Does not delete docs/versions/ — git history is preserved; the user decides when
+ *   to run `git rm -r --cached docs/`.
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+const Logger = require('../utils/logger');
+
+/**
+ * Migrates frozen snapshots from docs/versions/ to spec-versions/.
+ * @param {string} outputPath - The output directory defined in specs.json (e.g. './docs').
+ */
+function migrateVersionsToSpecVersions(outputPath) {
+    const src = path.join(outputPath, 'versions');
+    const dest = 'spec-versions';
+
+    if (!fs.existsSync(src)) {
+        // No old snapshots to migrate — nothing to do.
+        return;
+    }
+
+    // Check whether there are any version subdirectories (v1, v2, …) to migrate.
+    // We skip labels.json and index.html — those are regenerated automatically.
+    const versionDirs = fs.readdirSync(src).filter(entry =>
+        fs.statSync(path.join(src, entry)).isDirectory()
+    );
+
+    if (versionDirs.length === 0) {
+        return;
+    }
+
+    fs.ensureDirSync(dest);
+
+    let migratedCount = 0;
+
+    // Copy each version directory that does not already exist in spec-versions/.
+    versionDirs.forEach(dir => {
+        const srcDir = path.join(src, dir);
+        const destDir = path.join(dest, dir);
+
+        if (!fs.existsSync(destDir)) {
+            fs.copySync(srcDir, destDir);
+            migratedCount++;
+        }
+    });
+
+    // Always keep labels.json up to date in spec-versions/.
+    const srcLabels = path.join(src, 'labels.json');
+    const destLabels = path.join(dest, 'labels.json');
+
+    if (fs.existsSync(srcLabels)) {
+        if (!fs.existsSync(destLabels)) {
+            // No labels.json in spec-versions/ yet — copy the whole file.
+            fs.copySync(srcLabels, destLabels);
+        } else {
+            // Merge: preserve any entries already in spec-versions/labels.json
+            // and add any entries from docs/versions/labels.json that are missing.
+            const existing = fs.readJsonSync(destLabels);
+            const legacy = fs.readJsonSync(srcLabels);
+            const merged = { ...legacy, ...existing }; // spec-versions wins on conflict
+            fs.writeJsonSync(destLabels, merged, { spaces: 2 });
+        }
+    }
+
+    if (migratedCount > 0) {
+        Logger.success(
+            `Migrated ${migratedCount} snapshot(s) from ${src} to ${dest}/. ` +
+            `You can now safely run: git rm -r --cached ${outputPath}`
+        );
+    }
+}
+
+module.exports = migrateVersionsToSpecVersions;

package/src/install-from-boilerplate/select-template.js

@@ -0,0 +1,51 @@
+const readline = require('node:readline');
+const { templates } = require('./config-templates');
+const Logger = require('../utils/logger');
+
+/**
+ * Prompts the user to select a content template interactively.
+ * If the SPEC_UP_T_TEMPLATE environment variable is set, uses that value
+ * without prompting (for non-interactive use, e.g., GitHubUi or CI).
+ *
+ * @returns {Promise<Object>} The selected template object from config-templates.js
+ */
+function selectTemplate() {
+    // Check environment variable first (non-interactive use)
+    const envTemplate = process.env.SPEC_UP_T_TEMPLATE;
+    if (envTemplate) {
+        const found = templates.find(t => t.id === envTemplate);
+        if (found) {
+            Logger.info(`Using content template from environment: ${found.name}`);
+            return Promise.resolve(found);
+        }
+        Logger.warn(`Unknown template "${envTemplate}", falling back to default`);
+        return Promise.resolve(templates[0]);
+    }
+
+    return new Promise((resolve) => {
+        const rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout
+        });
+
+        console.log('\n📄 Available content templates:\n');
+        for (const [i, t] of templates.entries()) {
+            console.log(`  [${i}] ${t.name}`);
+            console.log(`      ${t.description}\n`);
+        }
+
+        rl.question('Select a content template (number) [0]: ', (answer) => {
+            rl.close();
+            const index = Number.parseInt(answer, 10);
+            if (!Number.isNaN(index) && index >= 0 && index < templates.length) {
+                Logger.info(`Selected template: ${templates[index].name}`);
+                resolve(templates[index]);
+            } else {
+                Logger.info('Using default template');
+                resolve(templates[0]);
+            }
+        });
+    });
+}
+
+module.exports = { selectTemplate, templates };

package/src/pipeline/configuration/prepare-spec-configuration.js

@@ -34,6 +34,12 @@ async function initializeConfig(options = {}) {
     const createExternalSpecsList = require('./create-external-specs-list.js');
     const externalSpecsList = createExternalSpecsList(config);
 
+    // Copy any frozen snapshots from the tracked spec-versions/ directory into
+    // the output path before regenerating the versions index. This is what makes
+    // locally-created or CI-created freezes survive a fresh checkout and redeploy.
+    const syncSpecVersions = require('./sync-spec-versions.js');
+    syncSpecVersions(config.specs[0].output_path);
+
     const createVersionsIndex = require('./create-versions-index.js');
     createVersionsIndex(config.specs[0].output_path);
 

package/src/pipeline/configuration/sync-spec-versions.js

@@ -0,0 +1,38 @@
+/**
+ * @file sync-spec-versions.js
+ * @description Copies the tracked spec-versions/ directory (at the consuming repo's
+ * root) into the output path's versions/ folder before the spec is rendered and
+ * deployed. This ensures that snapshots committed to the main branch are always
+ * included in the deployed specification, even after a completely fresh CI checkout
+ * where docs/ does not yet exist.
+ *
+ * spec-versions/ is the source of truth for frozen snapshots.
+ * docs/versions/   is the derived, deployable copy (gitignored, rebuilt every render).
+ *
+ * Does nothing when spec-versions/ does not exist — so repositories that have
+ * never run `npm run freeze` are not affected.
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+const Logger = require('../../utils/logger.js');
+
+/**
+ * Copies all contents of spec-versions/ into outputPath/versions/.
+ * The destination is created if it does not already exist.
+ * @param {string} outputPath - The output directory defined in specs.json (e.g. './docs').
+ */
+function syncSpecVersions(outputPath) {
+    const src = 'spec-versions';
+    const dest = path.join(outputPath, 'versions');
+
+    if (!fs.existsSync(src)) {
+        // No snapshots have been created yet — nothing to sync.
+        return;
+    }
+
+    fs.copySync(src, dest);
+    Logger.info(`Synced spec-versions/ → ${dest}`);
+}
+
+module.exports = syncSpecVersions;

package/src/pipeline/rendering/render-spec-document.js

@@ -40,6 +40,12 @@ async function render(spec, assets, sharedVars, config, template, assetsGlobal,
     // Get the branch name from which the index.html was generated
     const buildBranch = getCurrentBranch();
 
+    // Read spec-up-t version from its own package.json for build info display
+    const specUpTVersion = require('../../../package.json').version;
+
+    // Capture Node.js runtime version for build info display
+    const nodeVersion = process.version;
+
     // Read all markdown files into an array
     const docs = await Promise.all(
       (spec.markdown_paths || ['spec.md']).map(_path =>
@@ -166,6 +172,8 @@ async function render(spec, assets, sharedVars, config, template, assetsGlobal,
       currentDate: currentDate,
       universalTimestamp: universalTimestamp,
       buildBranch: buildBranch,
+      specUpTVersion: specUpTVersion,
+      nodeVersion: nodeVersion,
       githubRepoInfo: getGithubRepoInfo(spec)
     });
 

package/templates/template.html

@@ -325,6 +325,14 @@
                         <i class="bi bi-signpost-split me-2"></i>
                         <span>Source branch: <strong>${buildBranch}</strong></span>
                     </div>
+                    <div class="d-flex align-items-center mb-1">
+                        <i class="bi bi-box me-2"></i>
+                        <span>spec-up-t: <strong>v${specUpTVersion}</strong></span>
+                    </div>
+                    <div class="d-flex align-items-center mb-1">
+                        <i class="bi bi-cpu me-2"></i>
+                        <span>Node.js: <strong>${nodeVersion}</strong></span>
+                    </div>
                 </div>
             </div>
             <hr>