From 3a5023c071fed74d735769911598ca27ddcb9134 Mon Sep 17 00:00:00 2001 From: UnbreakableMJ Date: Fri, 19 Jun 2026 02:33:58 +0300 Subject: [PATCH] =?UTF-8?q?feat(spacecraft-standard):=20sync=20=C2=A78=20D?= =?UTF-8?q?ocumentation=20(Texinfo)=20=E2=80=94=20v1.24?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Mirror standard v1.24 changes: - Add §8 Documentation (Texinfo) section (§8.1–§8.6) - Renumber old §8–§15 → §9–§16 throughout (headers, body cross-refs, checklist) - Add §8 checklist bullet in §16 - Update Skill Cross-References with Texinfo row - Update frontmatter description and masthead to v1.24 / 2026-06-19 - Update intro text: "14-point checklist in §15" → "15-point checklist in §16" Co-Authored-By: Claude Sonnet 4.6 --- spacecraft-standard/SKILL.md | 144 +++++++++++++++++++++++++---------- 1 file changed, 102 insertions(+), 42 deletions(-) diff --git a/spacecraft-standard/SKILL.md b/spacecraft-standard/SKILL.md index 9f57c81..62f48a9 100644 --- a/spacecraft-standard/SKILL.md +++ b/spacecraft-standard/SKILL.md @@ -8,7 +8,7 @@ description: > Spacecraft Software-umbrella project — even if the user doesn't explicitly mention the Standard. If the user mentions "Spacecraft Software", a Spacecraft Software subproject name, or asks you to work on anything in the Spacecraft Software ecosystem, consult this skill immediately. It encodes - The Steelbore Standard v1.22 (§7 Shell Environment; §14.2 email obfuscation note) so + The Steelbore Standard v1.24 (§8 Documentation (Texinfo); §7 Shell Environment; §15.2 email obfuscation note) so you never need to ask for it or have it attached to a prompt again. license: GPL-3.0-or-later maintainer: Mohamed Hammad @@ -17,14 +17,14 @@ website: https://Construct.SpacecraftSoftware.org/ # The Steelbore Standard — Compliance Reference -**Version:** 1.22 | **Date:** 2026-06-18 | **Author:** Mohamed Hammad +**Version:** 1.24 | **Date:** 2026-06-19 | **Author:** Mohamed Hammad **Maintainer:** Mohamed Hammad | **Contact:** [Mohamed.Hammad@SpacecraftSoftware.org](mailto:Mohamed.Hammad@SpacecraftSoftware.org) **Copyright:** Copyright (C) 2026 Mohamed Hammad & Spacecraft Software | **License:** GPL-3.0-or-later **Website:** [https://Construct.SpacecraftSoftware.org/](https://Construct.SpacecraftSoftware.org/) This skill encodes The Steelbore Standard in full. Apply every applicable section -to any artifact you produce under the standard. The 14-point compliance checklist -in §15 is your audit gate — run through it mentally before finalising any output. +to any artifact you produce under the standard. The 15-point compliance checklist +in §16 is your audit gate — run through it mentally before finalising any output. > **License note:** This skill is `GPL-3.0-or-later` (skills are software-class, §4.1.1). > The *published* Standard document it encodes is licensed `CC-BY-SA-4.0`. @@ -109,7 +109,7 @@ back-rename. Existing legacy-named projects MAY be renamed under the v1.2 convention at the maintainer's discretion — renames are optional. When a rename happens, update -this table and §14.1's subdomain table in the same commit. +this table and §15.1's subdomain table in the same commit. ### §2.2 — Skill IDs are functional, not codenamed @@ -239,7 +239,7 @@ upstream's license in full — independent of the project's own GPL/AGPL choice: - **Ship** each distinct upstream license text in the project's `LICENSES/` directory (§4.3). - **Verify compatibility** of the upstream license with the project's GPL/AGPL license before inclusion. -- This is the legal/mechanical obligation; §14.3's `CREDITS.md` is the human-readable +- This is the legal/mechanical obligation; §15.3's `CREDITS.md` is the human-readable narrative counterpart. When both are triggered, both apply. ### §4.3 — SPDX & REUSE Compliance @@ -322,7 +322,7 @@ A project may declare itself **intended for general use**. When it does: semantic versioning, maintained `CHANGELOG.md`, deprecation policy, and a documented support window for the current major version. -**General-use registry** (keep in sync with §14.1 subdomain table): +**General-use registry** (keep in sync with §15.1 subdomain table): | Project | Posture | |--------------|---------------| @@ -410,7 +410,65 @@ Spacecraft Software tooling, documentation, and CI pipelines target **four first --- -## §8 — Privacy-Friendly Application (PFA) Policy +## §8 — Documentation (Texinfo) + +Spacecraft Software user-facing projects should ship a **Texinfo manual** as the canonical technical reference. Texinfo is the preferred format for reference documentation that accompanies distributed software, following GNU project conventions. + +### §8.1 — When a Texinfo Manual Is Required + +| Project type | Requirement | +|---|---| +| CLI / TUI / GUI application with substantive user-facing functionality | **MUST** ship a Texinfo manual covering invocation, options, concepts, and examples | +| Library with a public API | **SHOULD** ship a Texinfo reference manual covering all public interfaces | +| Simple script / internal tooling | **MAY** skip; a well-structured `README.md` suffices | + +### §8.2 — Source Format and File Layout + +- Source files use the `.texi` extension (Texinfo 7.x+). +- Manuals live at `doc/.texi` in the project root. +- The project's top-level `Makefile` must expose three targets: `make info`, `make html`, `make pdf`. + +### §8.3 — Required Structural Elements + +Every Texinfo manual must include the following elements: + +| Element | Purpose | +|---|---| +| `@dircategory` / `@direntry` | Registers the manual in the Info directory | +| `@copying` block | License statement and copyright notice | +| `@titlepage` | Title, version, author, and copyright | +| `@node Top` + `@top` | Required top-level node for Info readers | +| `@menu` per chapter | Navigation structure | + +### §8.4 — Output Formats + +Build and ship all three output formats: + +| Format | Tool | Purpose | +|---|---|---| +| `.info` | `makeinfo` / `texi2any` | Info readers (Emacs, standalone `info`) | +| `.html` | `makeinfo --html` | Project documentation website | +| `.pdf` | `texi2pdf` | Printable reference | + +Install `.info` files using `install-info` at package install time so they appear in the system Info directory. + +### §8.5 — Licensing + +Texinfo manuals are **document-class** artifacts (§4.1.1) and default to **CC-BY-SA-4.0**. **GFDL-1.3-or-later** is a permitted alternative when the manual is distributed alongside GPL-licensed software and compatibility with GNU documentation collections is desired. Include the chosen license in `LICENSES/` per §4.3. + +### §8.6 — Packaging Integration + +Package manifests must install the `.info` file and register it with `install-info`: + +| Package manager | Requirements | +|---|---| +| **Guix** (`packaging/guix.scm`) | Add `texinfo` as a native input; run `install-info` in the install phase | +| **Nix** (`packaging/default.nix`) | Add `texinfo` to `nativeBuildInputs`; standard Autoconf/Make `installPhase` handles `install-info` automatically | +| **PKGBUILD** (`packaging/PKGBUILD`) | Add `texinfo` to `makedepends`; `install -Dm644` for `.info` files; call `install-info` in `post_install` | + +--- + +## §9 — Privacy-Friendly Application (PFA) Policy Every Spacecraft Software application must satisfy **all three** PFA requirements: @@ -425,7 +483,7 @@ or networking, verify all three PFA requirements are met. --- -## §9 — Key Bindings +## §10 — Key Bindings All interactive applications must support **both**: @@ -436,7 +494,7 @@ All interactive applications must support **both**: --- -## §10 — Spacecraft Software Color Palette (WCAG-Compliant) +## §11 — Spacecraft Software Color Palette (WCAG-Compliant) The **only** permitted colors for Spacecraft Software interfaces and documents: @@ -455,7 +513,7 @@ No alternative background is permitted. This is non-negotiable. For document/file generation → load the `spacecraft-document-format` skill. For IDE/terminal themes → load the `spacecraft-theme-factory` skill. -### §10.1 — Steelbore Theme (Application Theming Standard) +### §11.1 — Steelbore Theme (Application Theming Standard) When building a new Spacecraft Software application (GUI, TUI, or web), all palette references **must** be accessed through a named theme called **`Steelbore`** rather than @@ -483,7 +541,7 @@ swap the theme, not every hex literal. --- -## §11 — Typography (FOSS-Licensed Fonts Only) +## §12 — Typography (FOSS-Licensed Fonts Only) Acceptable font licenses: **OFL, Apache 2.0, Ubuntu Font License, CC0-1.0** @@ -498,10 +556,10 @@ verify they are available on Google Fonts or another FOSS-licensed repository. --- -## §12 — UI/UX Design System +## §13 — UI/UX Design System - **Material Design** is the required component system for all graphical applications. - Theme Material components with the §10 color palette. + Theme Material components with the §11 color palette. - **WCAG 2.1 Level AA** contrast is the minimum for all color pairings. Any new color additions must be WCAG-verified before adoption. - **Accessibility:** screen readers, keyboard-only navigation, and system accessibility @@ -509,23 +567,23 @@ verify they are available on Google Fonts or another FOSS-licensed repository. --- -## §13 — Date, Time & Units +## §14 — Date, Time & Units -### §13.1 — Date & Time Format Rules +### §14.1 — Date & Time Format Rules | Concern | Rule | Example | |--------------|------------------------------------------------------------------|------------------------------| | Date format | ISO 8601 only: `YYYY-MM-DD` | `2026-03-08` | | Time format | 24-hour only: `HH:MM:SS` — AM/PM is **never** permitted | `14:30:00` | | Timestamp | Combined ISO 8601 UTC: `YYYY-MM-DDTHH:MM:SSZ` | `2026-03-08T14:30:00Z` | -| Timezone | **UTC Z is the default and preferred primary** for general-purpose, cross-system, and machine-readable timestamps. A project whose core domain is inherently local-time-bound (e.g., solar/prayer-time calculations) may declare local time as its primary record instead — a documented exception, not a free choice. See §13.2 and §13.2.1 | `Z` not `+00:00` | +| Timezone | **UTC Z is the default and preferred primary** for general-purpose, cross-system, and machine-readable timestamps. A project whose core domain is inherently local-time-bound (e.g., solar/prayer-time calculations) may declare local time as its primary record instead — a documented exception, not a free choice. See §14.2 and §14.2.1 | `Z` not `+00:00` | | Duration | ISO 8601 duration format only | `PT1H30M` not "1h 30m" | | Units | Metric (SI) primary; imperial in parentheses only if locale requires | `100 km (62 mi)` | Apply these conventions to all generated code, documentation, comments, and any user-facing strings. Never output AM/PM time, non-ISO dates, or imperial-primary units. -### §13.2 — UTC Z Timezone Policy +### §14.2 — UTC Z Timezone Policy **UTC Z is the default and preferred timezone for stored, transmitted, logged, and committed timestamps across Spacecraft Software projects.** It is the @@ -537,11 +595,11 @@ as a secondary, human-convenience field — but UTC Z remains the authoritative record. This is a strong default, not a universal mandate forced onto every domain -regardless of fit — §13.2.1 documents the exception that lets a project whose +regardless of fit — §14.2.1 documents the exception that lets a project whose domain is genuinely local-time-bound use local time as its primary record instead. **Rules for projects under the UTC Z default — apply unless a project has filed -the §13.2.1 exception:** +the §14.2.1 exception:** | Rule | Detail | |------|--------| @@ -552,7 +610,7 @@ the §13.2.1 exception:** | Commit timestamps use UTC | `GIT_COMMITTER_DATE` and `GIT_AUTHOR_DATE` must be UTC when set programmatically. | | File metadata written by Spacecraft Software tools | mtime/ctime written by Spacecraft Software tools must be UTC-sourced. | -### §13.2.1 — Domain Exception: Inherently Local-Time-Bound Projects +### §14.2.1 — Domain Exception: Inherently Local-Time-Bound Projects A project whose core domain is fundamentally defined by **local civil or solar time** — not by a moment in absolute (UTC) time — may declare local time as the @@ -569,7 +627,7 @@ would misrepresent what the data actually is. or user convenience. 2. **Keep the default everywhere else.** General-purpose machinery within the same project — logs, commit timestamps, internal cross-system APIs, - telemetry — still follows the §13.2 UTC Z default. The exception covers the + telemetry — still follows the §14.2 UTC Z default. The exception covers the domain data itself, not the whole project. 3. **Preserve UTC derivability.** Store or compute the IANA timezone (e.g., `Africa/Cairo`) alongside the local value, so a UTC instant remains derivable @@ -578,15 +636,15 @@ would misrepresent what the data actually is. convenient" or "our users are mostly in one timezone" do not qualify — the domain itself must be inherently local-time-bound. -### §13.3 — Local Time as Optional Companion +### §14.3 — Local Time as Optional Companion -**For projects under the UTC Z default** (§13.2), local time expressed as a UTC +**For projects under the UTC Z default** (§14.2), local time expressed as a UTC offset is permitted as an **optional companion** to the UTC Z primary value — in human-facing display, in API responses (as an additional field, never replacing the UTC Z field), and in stored records where timezone context aids human readers. The UTC Z value is always present and always authoritative; the local-time companion is supplemental only. (A project operating under the -§13.2.1 domain exception inverts these roles for its domain data — local time is +§14.2.1 domain exception inverts these roles for its domain data — local time is primary there, with UTC kept derivable rather than displayed as authoritative.) - The `--absolute-time` flag (defined in `spacecraft-cli-standard` §3) disables @@ -598,7 +656,7 @@ primary there, with UTC kept derivable rather than displayed as authoritative.) 4. Never persist or transmit the local-time rendering. - JSON/machine output (`--format json/jsonl/yaml/csv`) MUST always use UTC + `Z`. -### §13.4 — Duration Format +### §14.4 — Duration Format Durations follow ISO 8601 duration notation: @@ -611,7 +669,7 @@ Durations follow ISO 8601 duration notation: Prose forms like "1h 30m", "90 minutes", "1.5 hours" are **forbidden** in machine-readable output. They are acceptable in `--help` text only. -### §13.5 — Rust Implementation Guidance +### §14.5 — Rust Implementation Guidance When writing Rust code that handles time: @@ -627,14 +685,14 @@ When writing Rust code that handles time: --- -## §14 — Attribution, Maintainer & Contact +## §15 — Attribution, Maintainer & Contact **Maintainer:** Mohamed Hammad **Contact:** [Mohamed.Hammad@SpacecraftSoftware.org](mailto:Mohamed.Hammad@SpacecraftSoftware.org) **Copyright:** Copyright (C) 2026 Mohamed Hammad & Spacecraft Software | **License:** GPL-3.0-or-later **Website:** [https://SpacecraftSoftware.org/](https://SpacecraftSoftware.org/) -### §14.1 — Project Pages +### §15.1 — Project Pages Each Spacecraft Software project has a dedicated subdomain following the pattern `https://.SpacecraftSoftware.org/`. Use the project-specific URL in all @@ -668,7 +726,7 @@ project-level outputs; use `https://SpacecraftSoftware.org/` only for umbrella r When a new project is created, add its subdomain to this table immediately. -### §14.2 — Mandatory Attribution in Project Outputs +### §15.2 — Mandatory Attribution in Project Outputs Every Spacecraft Software product **must** surface the following attribution in at least one of: `--help` output, `--version` output, README, or About/Info screen. @@ -715,15 +773,15 @@ https://.SpacecraftSoftware.org/ always use the full address — those formats are parsed by `makepkg`/`pkgcheck` and `reuse lint` respectively, and obfuscation breaks them. -### §14.3 — Third-Party Attribution +### §15.3 — Third-Party Attribution Spacecraft Software artifacts must give credit where credit is due. When a project or skill **substantially builds on third-party work**, that credit appears in a `CREDITS.md` at the artifact's root — `/CREDITS.md` for projects, `/CREDITS.md` for skills. -`CREDITS.md` is the inbound counterpart to §14.2's outbound attribution: -§14.2 tells consumers who maintains Spacecraft Software; §14.3 tells consumers whose +`CREDITS.md` is the inbound counterpart to §15.2's outbound attribution: +§15.2 tells consumers who maintains Spacecraft Software; §15.3 tells consumers whose work Spacecraft Software stands on. **Triggers** (any one obligates a `CREDITS.md`): @@ -765,7 +823,7 @@ shaped the Spacecraft Software artifact. --- -## §15 — Compliance Checklist (Audit Gate) +## §16 — Compliance Checklist (Audit Gate) Before finalising **any** Spacecraft Software artifact, mentally verify: @@ -780,14 +838,15 @@ Before finalising **any** Spacecraft Software artifact, mentally verify: - [ ] **§5.5** Package distribution: `packaging/guix.scm`, `packaging/default.nix`, and `packaging/PKGBUILD` present, buildable, and carrying correct version + SHA-256 checksum (in each package manager's native format) before any release tag is pushed - [ ] **§6.1** POSIX-compliant CLI/system tools - [ ] **§7** Shell scripts are POSIX-compatible; Nushell/Ion native variants provided where shell-native idioms are required; no Bashisms in shared scripts -- [ ] **§8** PFA: no tracking, minimal permissions, local storage default -- [ ] **§9** CUA + Vim-like key bindings planned/implemented -- [ ] **§10** Spacecraft Software color palette used; Void Navy background mandatory; new apps expose colors via a named `Steelbore` theme (§10.1) — no bare hex literals in UI logic -- [ ] **§11** FOSS-licensed fonts only (Share Tech Mono / Inconsolata) -- [ ] **§12** Material Design UI/UX; WCAG 2.1 AA verified -- [ ] **§13** ISO 8601 dates; 24h time; UTC Z is the default primary timestamp (companion local time with UTC offset permitted, never a replacement) — unless the project filed the §13.2.1 domain exception for inherently local-time-bound data; ISO 8601 durations; metric units -- [ ] **§14** Attribution present: maintainer name (`Mohamed Hammad`), contact (`Mohamed.Hammad@SpacecraftSoftware.org`), and project URL in `--version` / README / About -- [ ] **§14.3** Third-party work credited in `CREDITS.md` at project/skill root when triggers apply; deeper `references/ATTRIBUTION.md` present where reference content is adapted from external sources +- [ ] **§8** Texinfo manual present for user-facing programs (`doc/.texi`); builds to `.info`, `.html`, and `.pdf`; `install-info` hook present in all three package manifests (§5.5) — N/A for scripts and internal tooling +- [ ] **§9** PFA: no tracking, minimal permissions, local storage default +- [ ] **§10** CUA + Vim-like key bindings planned/implemented +- [ ] **§11** Spacecraft Software color palette used; Void Navy background mandatory; new apps expose colors via a named `Steelbore` theme (§11.1) — no bare hex literals in UI logic +- [ ] **§12** FOSS-licensed fonts only (Share Tech Mono / Inconsolata) +- [ ] **§13** Material Design UI/UX; WCAG 2.1 AA verified +- [ ] **§14** ISO 8601 dates; 24h time; UTC Z is the default primary timestamp (companion local time with UTC offset permitted, never a replacement) — unless the project filed the §14.2.1 domain exception for inherently local-time-bound data; ISO 8601 durations; metric units +- [ ] **§15** Attribution present: maintainer name (`Mohamed Hammad`), contact (`Mohamed.Hammad@SpacecraftSoftware.org`), and project URL in `--version` / README / About +- [ ] **§15.3** Third-party work credited in `CREDITS.md` at project/skill root when triggers apply; deeper `references/ATTRIBUTION.md` present where reference content is adapted from external sources - [ ] **§6.3** All commits to Spacecraft Software Git remotes cryptographically signed with the `Mohamed.Hammad@SpacecraftSoftware.org` key and showing "Verified" on the hosting platform; rewrites preserve signatures; programmatic and assistant-driven commits signed too If any item is not applicable to the current artifact type (e.g., color palette @@ -802,6 +861,7 @@ for a pure Rust library), note it as N/A rather than silently skipping it. | Writing any Rust code | `microsoft-rust-guidelines` | | Writing or reviewing shell scripts | `spacecraft-cli-shell` + `spacecraft-cli-preference` | | Generating DOCX / ODT / PDF documents | `spacecraft-document-format` | +| Authoring a Texinfo manual | `spacecraft-standard` (§8) | | Creating IDE / terminal themes | `spacecraft-theme-factory` | | All other Spacecraft Software work | `spacecraft-standard` |