docs: scaffold the Integration Kit — front page, outline, and the checks
All checks were successful
PR Checks / template (pull_request) Successful in 6s
PR Checks / links (pull_request) Successful in 7s

Phase 5 slice 0 (MODULE_SYSTEM.md §2.11.1). The repo's governance, the front
page, the book's outline, and the CI that keeps the whole thing from rotting.

README.md
  What the reader is building, all three parts, and the draft banner: the kit is
  finished when someone outside this project builds a working module by
  following it alone, and that has not happened. Says the sidecar rule plainly
  (MODULE_API.md §2.7) rather than leaving it to chapter 3, because a reader who
  skims the front page and starts coding should still get that one right.

book/README.md
  The outline of four chapters, landed before the prose so the shape can be
  argued with. Chapters are named but NOT linked — a link to a file that does
  not exist is what the link check is for, and an outline should not be the
  first thing to fail it.

CONTRIBUTING.md
  The rule that governs every change here: the kit never re-specifies a
  contract. Also the prose conventions, and why the pinned ref points at core's
  `edge` rather than `main`.

SECURITY.md
  Scoped for a repo that runs nothing: the two things that ARE reportable are a
  template that teaches an insecure pattern (it is meant to be copied) and a
  chapter that teaches something dangerous.

scripts/checkLinks.js
  Relative links resolve; anchors match a real heading; no link pins a reader to
  a commit snapshot of a moving document. Nothing is fetched — a self-hosted
  Gitea would fail on a credential-less runner and teach us to ignore red.
  Fences and code spans are stripped by a line walk, not a regexp.

  Its first run found a real one: a PR template's relative links resolve from
  the REPO ROOT, because that is where their text ends up when Gitea inlines
  them into a pull request body. Encoded, with the reason.

scripts/checkCoreApi.js
  The anti-rot check. Asserts template/module.json's `coreApi` EQUALS the pinned
  core's MODULE_API_VERSION — equality, not "satisfies", because a range check
  stays green across a contract bump and green would then mean "the template
  still loads" instead of "someone has re-read the book". Both failure branches
  and the pass were exercised against a real core checkout.

ci/core-ref.json
  The pin, same convention as Module-uo's. Points at `edge`: core's `main` has
  no server/src/modules/ until the cutover, and that pin is one of the things
  the cutover has to revisit.

.gitea/workflows/pr-checks.yml
  Two jobs. `links` always runs; `template` is conditional on
  template/module.json existing, so the repo is gated now and the job arms
  itself when slice 1 lands, with no edit to the workflow. Same guard Module-uo
  used through its planning phase.

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
2026-08-12 09:47:22 -05:00
parent f9694be6a0
commit cffd525bdf
13 changed files with 991 additions and 0 deletions

View File

@@ -0,0 +1,45 @@
---
name: Something here is wrong
about: A chapter is inaccurate, an example does not work, or the template does not build
title: "[bug] "
labels:
- bug
---
## What is wrong
<!--
Which file, and which part of it. A chapter that no longer matches the
contract, an example that fails, a template that will not build, a dead link.
-->
## What happened
<!-- Exact commands and their output. Paste errors verbatim. -->
## What you expected
<!-- What the kit led you to believe would happen. -->
## Where you were
- File / chapter:
- Kit commit:
- Core version you built against (`MODULE_API_VERSION`), if known:
- Node version:
## Additional context
<!-- Anything else. Redact secrets and tokens. -->
<!--
Two things that are NOT bugs here, and where they go instead:
* A rule you disagree with. This kit teaches the contract and never defines
it — open that against MODULE_API.md in RunicGateway/docs.
* A core defect you hit while following along. That belongs in
RunicGateway/website.
Security issue? Do NOT file it here. See SECURITY.md and email
whitlocktech@gmail.com instead.
-->

View File

@@ -0,0 +1,8 @@
blank_issues_enabled: true
contact_links:
- name: Security vulnerability
url: https://gitea.whitlocktech.com/RunicGateway/Integration-kit/src/branch/main/SECURITY.md
about: Please do not open a public issue for security problems — report them privately by email instead (see SECURITY.md).
- name: The module contract itself
url: https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/website/MODULE_API.md
about: This repo teaches the contract but never defines it. If a rule looks wrong rather than badly explained, it belongs against MODULE_API.md in the docs repo.

View File

@@ -0,0 +1,39 @@
---
name: Something is missing
about: A question the kit left you unable to answer
title: "[gap] "
labels:
- enhancement
---
## What you were trying to do
<!--
The concrete thing. "I am building a module for <game> and I could not work out
how to …" is far more useful than "the docs should cover X".
-->
## Where you got stuck
<!--
Which chapter you were in when you ran out of information, and what you tried
next — searching core's source, guessing, giving up. The place a reader leaves
the kit is the most valuable thing you can tell us.
-->
## What you did in the end
<!-- If you solved it, how? That answer probably belongs in the kit. -->
## Is it a gap in the kit, or in the contract?
- [ ] The contract can already do this; the kit does not explain how.
- [ ] The contract cannot do this at all.
- [ ] Not sure.
<!--
If it is the contract, the kit cannot fix it — a module cannot register an
identity provider, for example, and that is recorded as a known boundary in
docs/modules/rust-dryrun.md. Say so anyway: a boundary a second reader hits is
evidence for changing MODULE_API.md.
-->