# KNELContracts

Public services contract (template) of **Known Element Enterprises LLC**
(management company of Turnkey Network Systems LLC) for the support services
it provides to Turnkey Network Systems LLC and the component/series LLCs
under it.

Each individual LLC (and Turnkey Network Systems LLC itself) will have a
private fork with a filled-out, executed copy of this contract (and the
operating agreement). The only permitted alterations in a fork are the ones
listed on the home page of the contract.

Work is tracked on Redmine:
<https://projects.knownelement.com/issues/924>

## Repository layout (Grav-native)

The repository IS the website content. There is no render pipeline —
no shell scripts, no mdbook, no templating. The Grav CMS renders it.

- `grav/user/pages/` — contract content (home, services, terms, sign,
  execution)
- `grav/user/themes/knel-contract/` — site theme, including the e-signature
  form page (targets the KNEL DocuSeal instance via the KNEL APISIX gateway;
  endpoints live in `grav/user/themes/knel-contract/knel-contract.yaml` so
  forks can retarget them)

## Sites

- **Release:** <https://contract.knownelement.com>
- **Branch previews:** `https://<branch>.contract.knownelement.com` — one
  Grav install per branch, kept in sync by the Grav Git Sync plugin.
  See [docs/branch-previews.md](docs/branch-previews.md).
  (Branch names are lowercased and non-alphanumeric characters become `-`
  to form the hostname.)

## Branching and pull requests

- `main` — **protected release branch.** Changes land ONLY via pull
  request; direct pushes are blocked by branch protection. Merging a PR to
  `main` is a human decision.
- `v0.1` — integration branch for the v0.1 contract stream (deployed
  content tracks this).
- Feature work happens on `feature/<topic>` branches, PR'd into `v0.1`.
  Releases are PR'd from `v0.1` into `main`.

## CI (lint on every PR)

Gitea Actions runs on every PR and on pushes to `main`/`v0.1`
(`.gitea/workflows/lint.yaml`):

| check | tool | blocking? |
|---|---|---|
| markdown lint | markdownlint-cli 0.41.0 | yes |
| spell check | typos v1.50.1 | yes |
| prose lint | vale v3.20.0 (proselint style) | no (advisory for now) |
| link check | lychee v0.20.0 | no (advisory for now) |

The goal: by the time a PR reaches a human reviewer, spelling, markdown
structure, prose quality, and link health have already been machine-checked.
Advisory checks graduate to blocking once their findings on the existing
content are triaged.

An `act_runner` must be registered on this repo (or the KNEL org) for the
workflow to execute.

## Deploys

Production deploys to contract.knownelement.com are production changes:
a GLPI CR is filed first, then the Grav content is synced into the app
(see docs/branch-previews.md for the LAMP/wildcard migration runbook).