spec-up-t 1.6.10 → 1.6.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-up-t",
-  "version": "1.6.10",
+  "version": "1.6.12",
   "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/install-from-boilerplate/boilerplate/.github/workflows/menu.yml

@@ -33,7 +33,8 @@ jobs:
   build-and-deploy-spec:
     runs-on: ubuntu-latest
     permissions:
-      contents: write  # Needed for pushing changes and deploying to Pages
+      contents: write   # Needed for pushing changes
+      actions: write    # Needed to dispatch render-and-deploy.yml
     steps:
       - name: Checkout 🛎️
         uses: actions/checkout@v4
@@ -68,7 +69,14 @@ jobs:
         run: |
           case "${{ github.event.inputs.action_type }}" in
             render)
-              npm run render
+              # Rendering is handled by render-and-deploy.yml.
+              # Dispatch that workflow to render and deploy to GitHub Pages.
+              curl -s -X POST \
+                -H "Authorization: token ${{ secrets.GITHUB_TOKEN }}" \
+                -H "Accept: application/vnd.github+json" \
+                "https://api.github.com/repos/${{ github.repository }}/actions/workflows/render-and-deploy.yml/dispatches" \
+                -d "{\"ref\":\"${{ github.ref_name }}\"}"
+              echo "render-and-deploy.yml dispatched"
               ;;
             topdf)
               npm run topdf
@@ -105,7 +113,8 @@ jobs:
           # Commit with appropriate message
           case "${{ github.event.inputs.action_type }}" in
             render)
-              git commit -m "Render specification: Update files" || echo "No changes to commit"
+              # render-and-deploy.yml already handles the commit/deploy; nothing to commit here.
+              echo "Render dispatched to render-and-deploy.yml — no direct commit needed"
               ;;
             topdf)
               git commit -m "Export to PDF" || echo "No changes to commit"
@@ -128,16 +137,7 @@ jobs:
           esac
           
           # Push changes
-          git push https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git HEAD:main
-
-      - name: Commit output files
-        if: success()
-        run: |
-          git config --global user.email "actions@github.com"
-          git config --global user.name "GitHub Actions"
-          git add "$OUTPUT_PATH"
-          git commit -m "Update output files in $OUTPUT_PATH" || echo "No changes to commit in output directory"
-          git push https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git HEAD:main
+          git push https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git HEAD:${{ github.ref_name }}
 
       - name: Clean up
         if: always()

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

@@ -0,0 +1,109 @@
+name: Render and Deploy to GitHub Pages
+
+# Triggered automatically on every push to main or master, or manually via
+# the Actions tab (or when dispatched by menu.yml for a render action).
+# Renders the specification and pushes the output to the gh-pages branch.
+# docs/ is NEVER committed to main/master.
+
+on:
+  push:
+    branches:
+      - main
+      - master
+    # Do not trigger on workflow file changes (.github/). Each workflow file
+    # is uploaded as a separate commit during repo creation, which would cause
+    # multiple competing runs in the same concurrency group. Real spec content
+    # changes (spec/, specs.json, package.json, etc.) still trigger a render.
+    # The initial render after repo creation is handled by an explicit dispatch.
+    # The trigger matrix is now:
+    #
+    # Event --> Triggers render?
+    #
+    # Push spec content (spec, specs.json, etc.) --> ✅ yes
+    # Push `.github/workflows/*.yml` (repo creation) --> ❌ no
+    # `workflow_dispatch` (GitHubUi "render" button, or menu.yml) --> ✅ yes
+    # PR into main/master --> ❌ not triggered (no `pull_request:` event)
+
+    paths-ignore:
+      - '.github/**'
+  workflow_dispatch:
+
+# Only allow one deployment at a time; do not cancel in-progress runs so that
+# a completed deploy is never replaced by a stale one.
+# NOTE: do NOT use 'pages' as the group name — that conflicts with GitHub's own
+# internal Pages deployment concurrency group and causes spurious cancellations.
+concurrency:
+  group: render-and-deploy-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  # ── Build & Deploy ────────────────────────────────────────────────────────────
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    # GitHub automatically generates a GITHUB_TOKEN for each workflow run.
+    # This ephemeral token is scoped only to the current repository and expires
+    # after the run completes. The 'permissions' block declares what this token
+    # is allowed to do — GitHub denies operations outside these scopes.
+    permissions:
+      contents: write # Required by peaceiris/actions-gh-pages to push to gh-pages
+      pages: write    # Required to configure GitHub Pages source via API
+    steps:
+      - name: Checkout 🛎️
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install dependencies 🔧
+        run: npm install
+
+      # Collect external references — this also renders the specification and
+      # writes output to the path defined in specs.json (output_path, typically ./docs/).
+      - name: Collect external references and render
+        run: npm run collectExternalReferences
+
+      # 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.
+      # Uses GITHUB_TOKEN (automatically injected by GitHub) with 'contents: write'
+      # permission to push to this repository.
+      - name: Deploy to GitHub Pages 🚀
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs
+          publish_branch: gh-pages
+
+      # Configure GitHub Pages to serve from the gh-pages branch (root /).
+      # This uses the GitHub REST API with GITHUB_TOKEN (permission: 'pages: write').
+      # It is idempotent — safe to run on every render (201=create, 409/422=exists, update).
+      # GITHUB_TOKEN is ephemeral (created per-run, expires at run end), scoped only to
+      # this repository, and never logged. GitHub accepts it because the token is issued
+      # by GitHub itself and this workflow declares 'pages: write' permission.
+      # continue-on-error: the API call may return a conflict on the very first run while
+      # GitHub is still processing the new gh-pages branch — this is non-fatal.
+      - name: Configure GitHub Pages source
+        continue-on-error: true
+        run: |
+          TOKEN="${{ secrets.GITHUB_TOKEN }}"
+          REPO="${{ github.repository }}"
+
+          HTTP_CODE=$(curl -s -o response.json -w "%{http_code}" \
+            -X POST \
+            -H "Authorization: token $TOKEN" \
+            -H "Accept: application/vnd.github+json" \
+            "https://api.github.com/repos/$REPO/pages" \
+            -d '{"source":{"branch":"gh-pages","path":"/"}}')
+
+          # 201 = created; 409/422 = already exists, update instead
+          if [ "$HTTP_CODE" -eq 409 ] || [ "$HTTP_CODE" -eq 422 ]; then
+            curl -s -o /dev/null \
+              -X PUT \
+              -H "Authorization: token $TOKEN" \
+              -H "Accept: application/vnd.github+json" \
+              "https://api.github.com/repos/$REPO/pages" \
+              -d '{"source":{"branch":"gh-pages","path":"/"}}'
+          fi
+          echo "GitHub Pages source set to gh-pages branch"

package/src/install-from-boilerplate/boilerplate/.github/workflows/set-gh-pages.yml

@@ -1,5 +1,10 @@
 name: Set GitHub Pages and Homepage
 
+# One-time setup workflow: run this AFTER the first successful
+# render-and-deploy run, which creates the gh-pages branch.
+# It configures GitHub Pages to serve from the gh-pages branch (root /)
+# and sets the repository homepage URL.
+
 on:
   workflow_dispatch:
 
@@ -7,93 +12,90 @@ jobs:
   configure-pages-and-homepage:
     runs-on: ubuntu-latest
     permissions:
-      contents: read  # To check branches
-      pages: write   # To configure Pages settings
+      contents: read
     steps:
-      - name: Check if gh-pages branch exists
-        id: check-branch
-        run: |
-          RESPONSE=$(curl -s -o /dev/null -w "%{http_code}" \
-            -H "Authorization: token ${{ secrets.MY_PAT }}" \
-            -H "Accept: application/vnd.github+json" \
-            https://api.github.com/repos/${{ github.repository }}/branches/gh-pages)
-          if [ "$RESPONSE" -eq 200 ]; then
-            echo "gh-pages branch exists"
-            echo "BRANCH_EXISTS=true" >> $GITHUB_ENV
-          elif [ "$RESPONSE" -eq 404 ]; then
-            echo "Error: gh-pages branch does not exist in ${{ github.repository }}"
-            exit 1
-          else
-            echo "Unexpected response code: $RESPONSE"
-            exit 1
-          fi
-
-      - name: Set GitHub Pages to gh-pages
-        if: env.BRANCH_EXISTS == 'true'
+      # Configure Pages to serve from the gh-pages branch (root /).
+      # POST creates the resource; a 409 means it already exists, so we PUT
+      # to update the source to the gh-pages branch.
+      - name: Enable GitHub Pages (gh-pages branch source)
         env:
           PAT: ${{ secrets.MY_PAT }}
         run: |
-          RESPONSE=$(curl -s -L \
+          HTTP_CODE=$(curl -s -L \
             -X POST \
             -H "Authorization: token $PAT" \
             -H "Accept: application/vnd.github+json" \
             https://api.github.com/repos/${{ github.repository }}/pages \
             -d '{"source":{"branch":"gh-pages","path":"/"}}' \
-            -w "%{http_code}" -o response.json)
-          if [ "$RESPONSE" -eq 201 ] || [ "$RESPONSE" -eq 200 ]; then
-            echo "GitHub Pages set to gh-pages branch for ${{ github.repository }}"
+            -w "%{http_code}" -o response.json | tail -n1)
+
+          if [ "$HTTP_CODE" -eq 201 ] || [ "$HTTP_CODE" -eq 200 ]; then
+            echo "GitHub Pages enabled with gh-pages branch as source"
+          elif [ "$HTTP_CODE" -eq 409 ]; then
+            echo "Pages already exists — updating source to gh-pages branch..."
+            HTTP_CODE2=$(curl -s -L \
+              -X PUT \
+              -H "Authorization: token $PAT" \
+              -H "Accept: application/vnd.github+json" \
+              https://api.github.com/repos/${{ github.repository }}/pages \
+              -d '{"source":{"branch":"gh-pages","path":"/"}}' \
+              -w "%{http_code}" -o response2.json | tail -n1)
+            if [ "$HTTP_CODE2" -eq 200 ] || [ "$HTTP_CODE2" -eq 204 ]; then
+              echo "GitHub Pages source updated to gh-pages branch"
+            else
+              echo "Failed to update Pages: $HTTP_CODE2"
+              cat response2.json
+              exit 1
+            fi
           else
-            echo "Failed to set GitHub Pages: $RESPONSE"
+            echo "Failed to configure Pages: $HTTP_CODE"
             cat response.json
             exit 1
           fi
 
+      # Set the repository homepage field to the expected GitHub Pages URL so
+      # it appears prominently on the repository landing page.
       - name: Set repository homepage to GitHub Pages URL
-        if: env.BRANCH_EXISTS == 'true'
         env:
           PAT: ${{ secrets.MY_PAT }}
         run: |
-          # Construct the expected GitHub Pages URL
           REPO_NAME=$(echo "${{ github.repository }}" | cut -d'/' -f2)
           OWNER=$(echo "${{ github.repository }}" | cut -d'/' -f1)
           PAGES_URL="https://${OWNER}.github.io/${REPO_NAME}"
 
-          # Set the homepage via API
-          RESPONSE=$(curl -s -L \
+          HTTP_CODE=$(curl -s -L \
             -X PATCH \
             -H "Authorization: token $PAT" \
             -H "Accept: application/vnd.github+json" \
             https://api.github.com/repos/${{ github.repository }} \
             -d "{\"homepage\":\"${PAGES_URL}\"}" \
-            -w "%{http_code}" -o response.json)
+            -w "%{http_code}" -o response.json | tail -n1)
 
-          if [ "$RESPONSE" -eq 200 ]; then
-            echo "Repository homepage set to $PAGES_URL for ${{ github.repository }}"
+          if [ "$HTTP_CODE" -eq 200 ]; then
+            echo "Repository homepage set to $PAGES_URL"
           else
-            echo "Failed to set homepage: $RESPONSE"
+            echo "Failed to set homepage: $HTTP_CODE"
             cat response.json
             exit 1
           fi
 
+      # Verify the homepage was written correctly.
       - name: Verify homepage matches GitHub Pages URL
-        if: env.BRANCH_EXISTS == 'true'
         env:
           PAT: ${{ secrets.MY_PAT }}
         run: |
-          # Construct the expected GitHub Pages URL
           REPO_NAME=$(echo "${{ github.repository }}" | cut -d'/' -f2)
           OWNER=$(echo "${{ github.repository }}" | cut -d'/' -f1)
           EXPECTED_URL="https://${OWNER}.github.io/${REPO_NAME}"
 
-          # Fetch the current homepage from the repo
           CURRENT_HOMEPAGE=$(curl -s -L \
             -H "Authorization: token $PAT" \
             -H "Accept: application/vnd.github+json" \
             https://api.github.com/repos/${{ github.repository }} | jq -r '.homepage')
 
           if [ "$CURRENT_HOMEPAGE" = "$EXPECTED_URL" ]; then
-            echo "Verified: Homepage is set to GitHub Pages URL ($EXPECTED_URL)"
+            echo "Verified: homepage is $EXPECTED_URL"
           else
-            echo "Error: Homepage ($CURRENT_HOMEPAGE) does not match expected GitHub Pages URL ($EXPECTED_URL)"
+            echo "Error: homepage ($CURRENT_HOMEPAGE) does not match $EXPECTED_URL"
             exit 1
           fi

package/src/install-from-boilerplate/boilerplate/gitignore

@@ -10,6 +10,9 @@
 # `.git/info/exclude` file instead of modifying the shared .gitignore.
 # Entries in `.git/info/exclude` stay completely local.
 
+# Generated by render-and-deploy.yml — do not commit build output
+docs/
+
 # Dependencies
 node_modules/
 

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-gitignore-entries.js

@@ -12,7 +12,9 @@ const gitIgnoreEntries = {
         '.env',
         'coverage',
         'build',
-        '.history'
+        '.history',
+        // Generated by render-and-deploy.yml — do not commit build output
+        'docs'
 ],
 };
 

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

@@ -3,6 +3,7 @@ const systemFiles = [
     '.env.example',
     'menu-wrapper.sh',
     '.github/workflows/menu.yml',
+    '.github/workflows/render-and-deploy.yml',
     '.github/workflows/set-gh-pages.yml',
     'assets/test.json',
     'assets/test.text',

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/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/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 };