// SPDX-License-Identifier: CC-BY-SA-4.0
// QUICKSTART-MAINTAINER.adoc — packaging and maintaining the standards bundle
= standards — Quick Start for Platform Maintainers
:toc:
:toclevels: 2

== Overview

This guide covers packaging, deploying, and maintaining standards for
distribution on your platform.

== Runtime Dependencies

This is a specs/standards monorepo, not a runtime application — "packaging"
means bundling the spec tree and its reference implementations.

* *Required:* `just`, `git`
* *Optional (to build/test reference impls):* `cargo` (Rust), `deno`, `zig`
* *Optional (reproducible env):* `guix` (primary) or `nix` (fallback)

== Build from Source

[source,bash]
----
git clone https://github.com/hyperpolymath/standards.git
cd standards
just build-release
----

Output: `spec bundle + reference-impl artefacts (no single binary)`

== Packaging

=== Guix

[source,bash]
----
guix build -f guix.scm
----

=== Nix

[source,bash]
----
nix build
----

=== Container (Stapeln)

[source,bash]
----
just stapeln-export    # Generates Containerfile
podman build -t standards .
----

=== Manual Package

[source,bash]
----
just install --prefix=/usr/local
----

Files installed:

[cols="1,2"]
|===
| Path | Contents

| `$PREFIX/bin/`
| Executables

| `$PREFIX/share/standards/`
| Data files, assets

| `$PREFIX/share/doc/standards/`
| Documentation

| `$PREFIX/share/applications/`
| .desktop file (Linux, if GUI)

| `$PREFIX/share/man/man1/`
| Man pages
|===

== Configuration

Default config location: `$XDG_CONFIG_HOME/standards/config.toml`

Fallback: `$HOME/.config/standards/config.toml`

== Health Checks

[source,bash]
----
just doctor            # Full diagnostic
just run --version   # Version check
just run --selftest  # Built-in self-test
----

== Updating

[source,bash]
----
git pull
just build-release
just install --prefix=/usr/local
----

Or via OPSM: `opsm update standards`

== Security Notes

* Licence: MPL-2.0 (see link:LICENSE[LICENSE])
* All dependencies SHA-pinned
* `panic-attacker` scan results: link:INSTALL-SECURITY-REPORT.adoc[]
* OpenSSF Scorecard: see badge in README

== Multi-Instance Deployment

For deploying multiple instances (e.g., different users or tenants):

[source,bash]
----
just install --prefix=/opt/standards-instance1 --config=/etc/standards/instance1.toml
just install --prefix=/opt/standards-instance2 --config=/etc/standards/instance2.toml
----

Each instance has isolated config, data, and logs.

== Reporting Issues

* Upstream: https://github.com/hyperpolymath/standards/issues
* With diagnostic: `just help-me` (pre-fills context)
