From 7029db903b67c48abe70b67f9ede19a599774bb2 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Tue, 29 Sep 2026 00:35:55 +0000 Subject: [PATCH] Add Tools Antora component scaffold and retire Grammaton from hub Introduce docs-tools/ as the hub-owned ROOT for the shared tools component, curate site-nav-tree to a single tools root, and remove grammaton-ui-shell from playbook sources. Rewrite Ecosystem for hub/architecture/Tools/cousins partitioning and point tool links at tools:: xrefs for sibling migration. Co-authored-by: Ryan Johnson --- .github/workflows/docs.yml | 1 + CHANGELOG.adoc | 6 ++++ README.md | 2 ++ antora-playbook-local.yml | 16 ++++------- antora-playbook.yml | 19 +++++-------- docs-tools/antora.yml | 6 ++++ docs-tools/modules/ROOT/nav.adoc | 1 + docs-tools/modules/ROOT/pages/index.adoc | 22 +++++++++++++++ docs/modules/ROOT/pages/ecosystem.adoc | 35 ++++++++++++++---------- docs/modules/ROOT/pages/index.adoc | 2 +- 10 files changed, 72 insertions(+), 38 deletions(-) create mode 100644 docs-tools/antora.yml create mode 100644 docs-tools/modules/ROOT/nav.adoc create mode 100644 docs-tools/modules/ROOT/pages/index.adoc diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index ba1770f..c9659ae 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -5,6 +5,7 @@ on: branches: [main, master] paths: - "docs/**" + - "docs-tools/**" - "lib/**" - "scripts/**" - "CONTRIBUTING.md" diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc index b9a0a35..4bcfc6d 100644 --- a/CHANGELOG.adoc +++ b/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::` for companion CLIs and libraries (sibling repos migrate to `name: tools` + `modules//`). + == 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. diff --git a/README.md b/README.md index 5438fa1..fe7bb33 100644 --- a/README.md +++ b/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 | diff --git a/antora-playbook-local.yml b/antora-playbook-local.yml index 6de0c60..50d9fae 100644 --- a/antora-playbook-local.yml +++ b/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 diff --git a/antora-playbook.yml b/antora-playbook.yml index 08d7443..c6bebd7 100644 --- a/antora-playbook.yml +++ b/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//. + - 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// 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 diff --git a/docs-tools/antora.yml b/docs-tools/antora.yml new file mode 100644 index 0000000..492b904 --- /dev/null +++ b/docs-tools/antora.yml @@ -0,0 +1,6 @@ +name: tools +title: Tools +version: ~ +start_page: ROOT:index.adoc +nav: + - modules/ROOT/nav.adoc diff --git a/docs-tools/modules/ROOT/nav.adoc b/docs-tools/modules/ROOT/nav.adoc new file mode 100644 index 0000000..2a80890 --- /dev/null +++ b/docs-tools/modules/ROOT/nav.adoc @@ -0,0 +1 @@ +* xref:index.adoc[Tools] diff --git a/docs-tools/modules/ROOT/pages/index.adoc b/docs-tools/modules/ROOT/pages/index.adoc new file mode 100644 index 0000000..ff49b0d --- /dev/null +++ b/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//` 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]. diff --git a/docs/modules/ROOT/pages/ecosystem.adoc b/docs/modules/ROOT/pages/ecosystem.adoc index ccb50bf..5d74d5b 100644 --- a/docs/modules/ROOT/pages/ecosystem.adoc +++ b/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) diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index 5bd30d3..7526688 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/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