Tools shared component scaffold; remove Grammaton from docs hub

.github/workflows/docs.yml

@@ -5,6 +5,7 @@ on:
     branches: [main, master]
     paths:
       - "docs/**"
+      - "docs-tools/**"
       - "lib/**"
       - "scripts/**"
       - "CONTRIBUTING.md"

CHANGELOG.adoc

@@ -1,5 +1,11 @@
 = Changelog
 
+== 2026-09-29 -- Tools shared Antora component
+
+* Add hub-owned `docs-tools/` scaffold (`name: tools`) with ROOT landing page; site-nav-tree lists a single `tools` root instead of per-CLI components.
+* Remove `Desktop-Tooling/grammaton-ui-shell` from playbook content sources; Ecosystem treats Grammaton as an external cousin, not an OSO Tools member.
+* Ecosystem and hub xrefs use `tools:<module>:` for companion CLIs and libraries (sibling repos migrate to `name: tools` + `modules/<id>/`).
+
 == 2026-09-27 -- Facto stack for docs.opensh.org
 
 * Adopt `@antora-supplemental/facto-stack` wiring: `indexify` URLs, site-nav-tree curated sidebar roots, nav-typology (+ Diátaxis), page-context/edit, link-validator, linkinator, extension-lister, orphan-finder, build-stack footer, client Mermaid + diagram lightbox, Kroki bake for non-Mermaid diagrams.

README.md

@@ -64,6 +64,7 @@ docs/                      # this repo (openshellorg/docs)
 ├── apps/
 │   └── main/              # Main website (SolidStart)
 ├── docs/                  # Antora hub component (SOS, philosophy, ecosystem)
+├── docs-tools/            # Antora `tools` component ROOT (member modules in sibling repos)
 ├── packages/
 │   ├── sos-grammar/       # @sos/grammar
 │   └── sos-validator-core/
@@ -77,6 +78,7 @@ docs/                      # this repo (openshellorg/docs)
 |------|-------------|
 | `apps/main` | Organization website (SolidStart) |
 | `docs/` | Hub Antora component (SOS + org pages) |
+| `docs-tools/` | Shared `tools` component landing (CLI/library manuals register as modules) |
 | `@sos/grammar` | Grammar definitions for parsing SOS syntax |
 | `@sos/validator-core` | Core validation logic for SOS compliance |
 

antora-playbook-local.yml

@@ -21,17 +21,11 @@ antora:
       include:
         - open-shell-org
         - shell-architecture
-        - about
-        - nu-require
-        - nu-emit
-        - project-map
+        - tools
       order:
         - open-shell-org
         - shell-architecture
-        - about
-        - nu-require
-        - nu-emit
-        - project-map
+        - tools
     - require: '@antora-supplemental/nav-typology'
     - require: '@antora-supplemental/nav-typology-diataxis'
     - '@antora-supplemental/build-stack'
@@ -60,6 +54,9 @@ content:
     - url: ./
       branches: HEAD
       start_path: docs
+    - url: ./
+      branches: HEAD
+      start_path: docs-tools
     - url: ../shell-architecture
       branches: HEAD
       start_path: docs
@@ -84,9 +81,6 @@ content:
     - url: ../project-map
       branches: HEAD
       start_path: docs
-    - url: ../grammaton-ui-shell
-      branches: HEAD
-      start_path: docs
     - url: ../terminal-gui-prompts
       branches: HEAD
       start_path: docs

antora-playbook.yml

@@ -25,17 +25,11 @@ antora:
       include:
         - open-shell-org
         - shell-architecture
-        - about
-        - nu-require
-        - nu-emit
-        - project-map
+        - tools
       order:
         - open-shell-org
         - shell-architecture
-        - about
-        - nu-require
-        - nu-emit
-        - project-map
+        - tools
     - require: '@antora-supplemental/nav-typology'
     - require: '@antora-supplemental/nav-typology-diataxis'
     - '@antora-supplemental/build-stack'
@@ -69,9 +63,14 @@ content:
     - url: ./
       branches: HEAD
       start_path: docs
+    # Hub-owned ROOT for the shared `tools` component; member repos must use name: tools + modules/<id>/.
+    - url: ./
+      branches: HEAD
+      start_path: docs-tools
     - url: https://github.com/openshellorg/shell-architecture.git
       branches: [main]
       start_path: docs
+    # Tools members (migrate antora.yml to name: tools + modules/<id>/ in each repo).
     - url: https://github.com/openshellorg/nu-emit.git
       branches: [main]
       start_path: docs
@@ -93,10 +92,6 @@ content:
     - url: https://github.com/openshellorg/project-map.git
       branches: [main]
       start_path: docs
-    # Grammaton UI Shell moved from openshellorg/actor-shell to Desktop-Tooling/grammaton-ui-shell
-    - url: https://github.com/Desktop-Tooling/grammaton-ui-shell.git
-      branches: [main]
-      start_path: docs
     - url: https://github.com/openshellorg/terminal-gui-prompts.git
       branches: [main]
       start_path: docs

docs-tools/antora.yml

@@ -0,0 +1,6 @@
+name: tools
+title: Tools
+version: ~
+start_page: ROOT:index.adoc
+nav:
+  - modules/ROOT/nav.adoc

docs-tools/modules/ROOT/nav.adoc

@@ -0,0 +1 @@
+* xref:index.adoc[Tools]

docs-tools/modules/ROOT/pages/index.adoc

@@ -0,0 +1,22 @@
+= Tools
+:description: Installable OpenShellOrg CLIs and libraries documented on this hub.
+:page-audience: Practitioners, CLI authors, and doc readers browsing the hub
+:page-usage-context: When you need an OSO companion CLI or library and want the canonical docs entry point
+:page-orig-author: agent on behalf of OpenShellOrg
+:page-last-author: agent on behalf of OpenShellOrg
+:page-last-edited: 2026-09-29
+
+*Tools* is the shared Antora component for installable OpenShellOrg command-line utilities and companion libraries whose manuals are assembled on https://docs.opensh.org/[docs.opensh.org]. Each member publishes under `modules/<id>/` in its own repository; this hub owns the ROOT landing page and site navigation root for the partition.
+
+Member manuals (links activate as sibling repos finish migrating to `name: tools`):
+
+* xref:about:index.adoc[about] — machine orientation and OS-family cheat sheets
+* xref:nu-require:index.adoc[nu-require] — require Nushell as host, relaunch, or install path
+* xref:nu-emit:index.adoc[nu-emit] — structured JSONL rows from C (and bindings) for Nushell pipelines
+* xref:project-map:index.adoc[project-map] — project-type and file-role classification; grouped directory listing
+* xref:info:index.adoc[info] — modern GNU Info TUI
+* xref:prohelp:index.adoc[prohelp] — progressive help engine and global `help`
+* xref:prohelp-cli:index.adoc[prohelp-cli] — bridges into D CLI frameworks
+* xref:terminal-gui-prompts:index.adoc[terminal-gui-prompts] — native GUI confirm/input with echoed prompt text for pipes
+
+Hub-wide map of standards, architecture, Tools, and external cousins: xref:open-shell-org::ecosystem.adoc[Ecosystem].

docs/modules/ROOT/pages/ecosystem.adoc

@@ -1,7 +1,7 @@
 = Ecosystem
-:description: OpenShellOrg documentation components across sibling repositories.
+:description: How OpenShellOrg documentation on this hub is partitioned.
 
-OpenShellOrg docs are assembled from multiple Antora components — one per main project.
+The docs site is a small set of overlapping partitions: this hub (*open-shell-org*), *shell-architecture*, the shared *tools* component for installable OSO CLIs and libraries, and external cousins (PlayTime, DevCentr, desktop products) that are linked but not assembled here.
 
 == Standards and explanation
 
@@ -21,27 +21,34 @@ link:https://github.com/AMDphreak/connectome-fs[connectome-fs] owns node/edition
 * link:https://amdphreak.github.io/connectome-fs/manual/connectome-fs/0.1/explanation/shell-query-surface.html[Shell query surface]
 * link:https://amdphreak.github.io/connectome-fs/manual/connectome-fs/0.1/explanation/compatibility-projection.html[Compatibility projection]
 
-== Companion libraries
+== Tools
 
-* xref:nu-require::index.adoc[nu-require] — require / relaunch under Nushell
-* xref:nu-emit::index.adoc[nu-emit] — emit structured JSONL rows from C
-* https://github.com/openshellorg/project-map[project-map] / `lsgrouped` — project-type + file-role classification; grouped directory listing (not a PATH `ls` replacement)
+Installable OSO CLIs and companion libraries documented on this hub share one Antora component (`tools`). Landing page: xref:tools::index.adoc[Tools].
+
+=== Companion libraries
+
+* xref:tools:nu-require:index.adoc[nu-require] — require / relaunch under Nushell
+* xref:tools:nu-emit:index.adoc[nu-emit] — emit structured JSONL rows from C
+* xref:tools:project-map:index.adoc[project-map] — project-type + file-role classification; grouped directory listing (not a PATH `ls` replacement)
 * https://github.com/openshellorg/config-lifecycle[config-lifecycle] — classify / match / alert for config keys (`active` / `deprecated` / `expired` / `unknown`); never drop expired detection — xref:standard-config-lifecycle-management.adoc[Config Lifecycle Management]
 
-== Planned / forked products
+=== Orientation and help
+
+* xref:tools:about:index.adoc[about] — machine orientation + command cards
+* xref:tools:info:index.adoc[info] — modern GNU Info TUI
+* xref:tools:prohelp:index.adoc[prohelp] — progressive help engine + global `help`
+* xref:tools:prohelp-cli:index.adoc[prohelp-cli] — bridges into D CLI frameworks
+* xref:tools:terminal-gui-prompts:index.adoc[terminal-gui-prompts] — promote confirm/input to native GUI dialogs; always echo prompt text for pipes
+
+== Planned shell products
 
 Spec and ownership live in shell-architecture:
 
 * xref:shell-architecture::shell-host-and-env-refresh.adoc[env-refresh + terminal fork] — Nu-first `env-refresh` CLI (planned) and https://github.com/openshellorg/terminal[`openshellorg/terminal`] (fork of Windows Terminal) with per-tab env health + Fix/Insert desync bar; DevCentr prefers these when installed
-* xref:grammaton-ui-shell::index.adoc[Grammaton UI Shell] — non-frustrating Windows/Linux UI shell on an Erlang-style actor runtime (D); Phase 1 `libbeam_d` landed (formerly actor-shell; now `Desktop-Tooling/grammaton-ui-shell`)
 
-== Orientation and help
+== Cousin products (outside this hub)
 
-* xref:about::index.adoc[about] — machine orientation + command cards
-* xref:info::index.adoc[info] — modern GNU Info TUI
-* xref:prohelp::index.adoc[prohelp] — progressive help engine + global `help`
-* xref:prohelp-cli::index.adoc[prohelp-cli] — bridges into D CLI frameworks
-* xref:terminal-gui-prompts::index.adoc[terminal-gui-prompts] — promote confirm/input to native GUI dialogs; always echo prompt text for pipes
+* https://github.com/Desktop-Tooling/grammaton-ui-shell[Grammaton UI Shell] — Desktop-Tooling UI shell on an Erlang-style actor runtime (not an OpenShellOrg Tools member)
 
 == PlayTime (cousin, not a component here)
 

docs/modules/ROOT/pages/index.adoc

@@ -16,6 +16,6 @@ Read more: xref:philosophy.adoc[Philosophy].
 
 == Where next
 
-* xref:ecosystem.adoc[Ecosystem] — map of every docs component
+* xref:ecosystem.adoc[Ecosystem] — hub, architecture, Tools, and external cousins
 * xref:standard-intro.adoc[SOS Introduction] — start the standard
 * xref:shell-architecture::index.adoc[shell-architecture] — structured-shell thesis