@futurelastic/colab-handbook 1.22.1-rc.1 → 1.22.1-rc.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -33,5 +33,5 @@
33
33
  "engines": {
34
34
  "node": ">=18"
35
35
  },
36
- "version": "1.22.1-rc.1"
36
+ "version": "1.22.1-rc.3"
37
37
  }
@@ -95,7 +95,7 @@ header naming its new home ([`docs/compat-surfaces.md`](../docs/compat-surfaces.
95
95
  | `pre-commit-dispatch`, `pre-commit-identity`, `identity-vocabulary.example` | git (this repo's own `.githooks/` run them in place) | stays here, as an optional starting file |
96
96
  | `pre-commit-instruction-files`, `instruction-files.yml` | `colab instruction-files`; the reusable workflow in this repo | the `colab instruction-files` command; the reusable workflow is the one remote call this folder keeps, for compatibility |
97
97
  | `docs-lint.mjs`, `docs-lint.yml`, `branch-name.yml` | your CI (advisory or opt-in); `code-wrap`'s docs step | stays here, as an optional starting file |
98
- | `repo-CLAUDE-block.md`, `gotchas-d-README.md`, `adr-README.md` | nothing — text you paste or copy (`colab adopt` pastes the block) | stays here |
98
+ | `repo-CLAUDE-block.md`, `gotchas-d-README.md`, `adr-README.md`, `docs-README.md` | nothing — text you paste or copy (`colab adopt` pastes the block) | stays here |
99
99
 
100
100
  Nothing in this table changes what a copied file does. A stamp, a drift report or a `colab`
101
101
  check that reads one of these files is that tool's behaviour, documented with the tool.
@@ -124,7 +124,8 @@ check that reads one of these files is that tool's behaviour, documented with th
124
124
  | `repo-CLAUDE-block.md` | *paste into* `CLAUDE.md` | Every adopting repo | The discovery hook — how an agent finds the handbook at all. |
125
125
  | `gotchas-d-README.md` | `docs/gotchas.d/README.md` | Any repo starting a `docs/gotchas.d/` directory ([`code-wrap`](../skills/code-wrap/SKILL.md)'s A2 step) | Naming rule (`<issue>-<slug>.md`) and the don't-copy-back rule against an existing `docs/gotchas.md`. Optional — writing the first gotcha entry does not require copying this in first. |
126
126
  | `adr-README.md` | `docs/adr/README.md` | Any repo starting a `docs/adr/` directory ([`code-wrap`](../skills/code-wrap/SKILL.md)'s A2 step) | Same issue-keyed naming rule as `gotchas-d-README.md`, applied to architecture decision records instead of gotchas — an existing sequentially-numbered `docs/adr/` is left as-is; only new decisions use `<issue>-<slug>.md`. Optional, same as above. |
127
- | `docs-lint.mjs` | anywhere in-repo (e.g. `tools/docs-lint.mjs`) | Every repo — checks the STRUCTURE of the doc graph (router integrity, orphans, drafts-in-`docs/`, router size budget, dated files, §-citation resolution, `gotchas.d/` registry discipline, two-surface linkage) | Zero-dependency, plain Node — but it does **shell out to `git check-ignore`** once per enumeration, so that a git-ignored scratch file (your `.plans/` plan file, say) can never fail a structural check on your repo (#310). No git, or no repo, and it filters nothing and lints exactly as before. **Enumerated by `colab template` and DOES take an automatic version stamp** (colab-handbook #252): `colab template docs-lint.mjs --dest tools/docs-lint.mjs` copies it stamped on its **second** line (`// colab-handbook: docs-lint @ <version>`, after the `#!/usr/bin/env node` shebang — a bare `#` on any other line is a JS syntax error, unlike the YAML templates above) — `--dest` is required, since this file has no formulaic destination the way a workflow does. Pairs with `docs-lint.yml`. Also runs from `code-wrap`'s docs step and a weekly fleet sweep (colab-handbook #249) — this row is the third of its three seats. |
127
+ | `docs-README.md` | `docs/README.md` | Any repo whose `docs/` has three or more root entries and no index (`handbook-sync` offers it at adoption; [`code-wrap`](../skills/code-wrap/SKILL.md)'s A2 *`docs/` layout*, #686) | The index: one line per root entry, the `merge=union` line for `.gitattributes`, the reserved root names and the layout in brief. Delete the example lines you do not have yet. Optional — a repo may write its index by hand. |
128
+ | `docs-lint.mjs` | anywhere in-repo (e.g. `tools/docs-lint.mjs`) | Every repo — checks the STRUCTURE of the doc graph (router integrity, orphans, drafts-in-`docs/`, router size budget, dated files, §-citation resolution, `gotchas.d/` registry discipline, two-surface linkage) and, as WARN only, the `docs/` layout (#686: the index, plan/report and dated names, non-kebab names, design artifacts outside `design/<slug>-<N>/`, images over 1 MB, fonts outside `design/_assets/`) | Zero-dependency, plain Node — but it does **shell out to `git check-ignore`** once per enumeration, so that a git-ignored scratch file (your `.plans/` plan file, say) can never fail a structural check on your repo (#310). No git, or no repo, and it filters nothing and lints exactly as before. **Enumerated by `colab template` and DOES take an automatic version stamp** (colab-handbook #252): `colab template docs-lint.mjs --dest tools/docs-lint.mjs` copies it stamped on its **second** line (`// colab-handbook: docs-lint @ <version>`, after the `#!/usr/bin/env node` shebang — a bare `#` on any other line is a JS syntax error, unlike the YAML templates above) — `--dest` is required, since this file has no formulaic destination the way a workflow does. Pairs with `docs-lint.yml`. Also runs from `code-wrap`'s docs step and a weekly fleet sweep (colab-handbook #249) — this row is the third of its three seats. |
128
129
  | `docs-lint.yml` | `.github/workflows/docs-lint.yml` | Every repo that copied `docs-lint.mjs` | Advisory job — `continue-on-error: true` on the lint step, so a finding never blocks a merge until a repo deliberately removes that line. Requires `docs-lint.mjs` to already be in the repo; does not vendor it. |
129
130
  | `instruction-files.yml` | `.github/workflows/instruction-files.yml` | Every repo with a `CLAUDE.md` (#588) | **A caller, not a copy:** its one job `uses:` the handbook's reusable `.github/workflows/instruction-files.yml`, so the judgement is maintained once and works from any org. Fails when a `CLAUDE.md` carries repo prose instead of `@AGENTS.md` + tool blocks — **ratcheted**: only when the change touches `CLAUDE.md`/`AGENTS.md`, or the repo had already migrated. An unmigrated repo stays green until it edits those files. Pin `@<tag>` plus `with: handbook-ref: <tag>` to freeze the checker. No GitHub-hosted minutes (self-hosted-only org)? `with: runs-on: <label>` or a JSON list `'["self-hosted","linux"]'` (#594) — any Linux runner with git; the job sets up its own Node. |
130
131
  | `branch-name.yml` | `.github/workflows/branch-name.yml` | Opt-in — any repo that wants §4's branch shape checked on every PR | One step, no dependencies: the PR's head branch against CONVENTIONS.md §4's regex, both shapes (`<type>/<slug>-<N>` and the `<login>/<machine>/` prefixed one) passing as shipped. Once the repo declares `branchPrefix: machine`, delete the `?` after the regex's first group to require the prefix. The head ref reaches the script through `env:`, never interpolated — on a public repo it is attacker-chosen. |
@@ -37,15 +37,30 @@
37
37
  # artifact per platform named `<artifact-prefix><os>-<arch>`, then:
38
38
  #
39
39
  # dist:
40
- # needs: [build] # your matrix build, one upload-artifact per platform
40
+ # needs: [build] # your matrix build, one artifact-store/upload per platform
41
41
  # uses: ./.github/workflows/dist-refs.yml
42
42
  # permissions:
43
43
  # contents: write
44
+ # secrets: inherit # the artifact-store secrets below — a called workflow
45
+ # # reads no secret it is not passed
44
46
  # with:
45
47
  # version: ${{ needs.release.outputs.tag }} # vX.Y.Z or vX.Y.Z-rc.N
46
48
  # platforms: darwin-arm64 darwin-x64 linux-x64 linux-arm64 win32-x64
47
49
  # bin: mytool # EDIT: the launcher's binary name
48
50
  #
51
+ # THE ARTIFACTS GO THROUGH YOUR ARTIFACT STORE, not GitHub's capped artifact allowance
52
+ # (CONVENTIONS.md §7, "CI artifacts", #601). The build uploads each platform with
53
+ # artifact-store/upload, and the download step below reads them back with
54
+ # artifact-store/download, both with the same five secrets: ARTIFACT_STORE_ENDPOINT,
55
+ # ARTIFACT_STORE_BUCKET, ARTIFACT_STORE_ACCESS_KEY, ARTIFACT_STORE_SECRET_KEY and
56
+ # ARTIFACT_STORE_REGION (docs/artifact-store.md in the handbook). Pass them with
57
+ # `secrets: inherit` as above, or one by one under `secrets:`. With no bucket secret the
58
+ # download runs with `backend: github`, i.e. GitHub's own artifact action, so a copy works
59
+ # before its store exists — the build's uploads must then use the same fallback.
60
+ # ⚠ REGION: requests are signed for the region and default to us-east-1. A store configured
61
+ # with any other region answers 400 to every GET signed for the wrong one, so set
62
+ # ARTIFACT_STORE_REGION and pass it on every call site, uploads included.
63
+ #
49
64
  # Each artifact must hold the binary at its top level, named `<bin>` (`<bin>.exe` on win32-*).
50
65
  # Anything else in the artifact rides along in the same ref and is covered by SHA256SUMS.
51
66
  #
@@ -92,6 +107,24 @@ on:
92
107
  required: false
93
108
  type: string
94
109
  default: 'dist-'
110
+ # The artifact store's connection (#601). All optional: with no bucket the download falls
111
+ # back to GitHub's artifact action. `secrets: inherit` from the caller passes them too.
112
+ secrets:
113
+ ARTIFACT_STORE_ENDPOINT:
114
+ description: 'S3 endpoint URL. Empty means the AWS default endpoint.'
115
+ required: false
116
+ ARTIFACT_STORE_BUCKET:
117
+ description: 'Bucket the build uploaded to. Empty = backend github.'
118
+ required: false
119
+ ARTIFACT_STORE_ACCESS_KEY:
120
+ description: 'Access key id for the store.'
121
+ required: false
122
+ ARTIFACT_STORE_SECRET_KEY:
123
+ description: 'Secret access key for the store.'
124
+ required: false
125
+ ARTIFACT_STORE_REGION:
126
+ description: 'Region the store signs for. Empty means us-east-1.'
127
+ required: false
95
128
 
96
129
  permissions:
97
130
  contents: write
@@ -120,10 +153,26 @@ jobs:
120
153
  with:
121
154
  fetch-depth: 1
122
155
 
123
- - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
156
+ # Through the artifact store (#601): the secrets and the region trap are in the header.
157
+ # EDIT: `@HANDBOOK_TAG` is the handbook release this copy calls — `colab template` writes
158
+ # the version it stamps; by hand, pin a tag or a commit, never a branch. Copied the action
159
+ # into this repo instead? `uses: ./.github/actions/artifact-store/download`.
160
+ - name: Download the per-platform artifacts
161
+ uses: futurelastic/colab-handbook/.github/actions/artifact-store/download@HANDBOOK_TAG
124
162
  with:
163
+ # Empty name + pattern = every `<artifact-prefix>*` artifact of this run, each in
164
+ # dist-in/<name>/ — the layout the push step reads.
125
165
  pattern: ${{ inputs.artifact-prefix }}*
126
166
  path: dist-in
167
+ # No bucket secret → GitHub's own artifact action, unchanged. The bucket, not the
168
+ # endpoint, decides: an empty endpoint is a real store (the AWS default), a missing
169
+ # bucket is none.
170
+ backend: ${{ secrets.ARTIFACT_STORE_BUCKET != '' && 's3' || 'github' }}
171
+ endpoint: ${{ secrets.ARTIFACT_STORE_ENDPOINT }}
172
+ bucket: ${{ secrets.ARTIFACT_STORE_BUCKET }}
173
+ access-key: ${{ secrets.ARTIFACT_STORE_ACCESS_KEY }}
174
+ secret-key: ${{ secrets.ARTIFACT_STORE_SECRET_KEY }}
175
+ region: ${{ secrets.ARTIFACT_STORE_REGION }}
127
176
 
128
177
  - name: Push one orphan ref per platform
129
178
  env:
@@ -0,0 +1,39 @@
1
+ # `docs/` — what lives here
2
+
3
+ The index of this repo's `docs/`: **one line per root entry**, file or folder. A folder's own
4
+ contents are listed by its own `README.md`, not here. Add the line in the same commit that adds
5
+ the entry; a file no line names is one nobody will find.
6
+
7
+ Keep this file's merges conflict-free — `.gitattributes` carries:
8
+
9
+ ```gitattributes
10
+ docs/README.md merge=union
11
+ ```
12
+
13
+ Two branches that each add a line then merge cleanly; check the order by eye afterwards.
14
+
15
+ ## Entries
16
+
17
+ <!-- One line each, in this shape. Delete the examples you do not have yet: reserved names are
18
+ created when their first content arrives, never as empty placeholders. -->
19
+
20
+ - [`architecture.md`](architecture.md) — the system as it is now, edited in place.
21
+ - [`deploy.md`](deploy.md) — how this repo reaches production, and its runbook.
22
+ - [`adr/`](adr/README.md) — one file per decision, `<issue>-<slug>.md`.
23
+ - [`gotchas.d/`](gotchas.d/README.md) — one file per long-lived gotcha, `<issue>-<slug>.md`.
24
+ - [`design/`](design/README.md) — one folder per design issue, `design/<slug>-<N>/`.
25
+
26
+ ## The layout, in brief
27
+
28
+ The full rule is `code-wrap` A2, *The `docs/` layout*, in the colab-handbook.
29
+
30
+ - **Current truth only.** Plans, proposals, reports, audits and session notes go on the Issue,
31
+ never in `docs/`.
32
+ - **Names:** lower-kebab-case, no dates; the issue number is the only key (`README.md` excepted).
33
+ - **Reserved root names:** `architecture.md`, `deploy.md`, `operations.md`, `data.md`,
34
+ `design-spec.md`, `guides/`, `reference/` — plus `adr/`, `gotchas.d/`, `design/`.
35
+ - **Design artifacts:** `design/<slug>-<N>/` holds `<slug>-<N>-spec.md`, `<slug>-<N>-mockup.html`
36
+ and `frames/`. Fonts and shared CSS live once, in `design/_assets/`, or are linked from the
37
+ design-system package.
38
+ - **Binaries stay light:** an image over 1 MB is exported smaller.
39
+ - **Existing files stay where they are** (lazy migration); new entries follow the layout.
@@ -12,6 +12,12 @@
12
12
  // know whether a gotcha is still true; that stays with `code-wrap`'s stale-docs
13
13
  // step and a human hygiene pass. This split is deliberate (colab-handbook #249).
14
14
  //
15
+ // Checks 9-14 (colab-handbook #686) read the `docs/` LAYOUT `code-wrap` A2
16
+ // states: an index (`docs/README.md`, one line per root entry), no plan/
17
+ // proposal/report/audit or dated names, lower-kebab-case names, one folder per
18
+ // design issue (`docs/design/<slug>-<N>/`), images under 1 MB, and fonts only
19
+ // in `docs/design/_assets/`. All WARN — existing files may stay where they are.
20
+ //
15
21
  // ZERO DEPENDENCIES. Plain Node (>= 18), no npm install, no package.json needed
16
22
  // to run it — only `node:fs`, `node:path`, (for the receipt hashes below) the
17
23
  // builtin `node:crypto`, and `node:child_process` to shell out to `git
@@ -428,6 +434,9 @@ const LINK_RE = /\]\(([^)#\s]*\.md)?#?([^)\s]*)\)/g;
428
434
  // A simpler "does this file link anywhere" scanner for the orphan check
429
435
  // (check 2), which only needs the TARGET path, not the fragment.
430
436
  const ANY_MD_LINK_RE = /\]\(([^)#\s]+\.md)(#[^)\s]*)?\)/g;
437
+ // Any link target, markdown or not (`](adr/)`, `](design/README.md)`) — the
438
+ // index check (9) asks which docs/ root entries a link reaches, files or folders.
439
+ const ANY_LINK_TARGET_RE = /\]\(([^)#\s]+)(#[^)\s]*)?\)/g;
431
440
 
432
441
  function isExternalTarget(t) {
433
442
  return /^[a-z][a-z0-9+.-]*:/i.test(t) || t.startsWith("//");
@@ -925,6 +934,254 @@ function checkTwoSurfaceLinkage(ctx) {
925
934
  return { receipt };
926
935
  }
927
936
 
937
+ // ===========================================================================
938
+ // Checks 9-14 — the docs/ LAYOUT (colab-handbook #686; `code-wrap` A2,
939
+ // a2-docs-layout.md). Every one is WARN: a layout finding is a tidy-up for the
940
+ // repo's own issue, never a broken reference, and existing files are allowed
941
+ // to stay where they are (lazy migration). They read FILE NAMES, not content,
942
+ // and they see every file under docs/ — not only markdown — because the
943
+ // patterns they look for (a 6 MB screenshot, a font copied into a design
944
+ // folder, a loose mockup.html) are mostly not markdown.
945
+ // ===========================================================================
946
+
947
+ // Every file under docs/ (any extension), repo-relative, git-ignore filtered.
948
+ // Cached on ctx: six checks share one walk and one `git check-ignore` call.
949
+ function docsAllFiles(ctx) {
950
+ if (ctx.docsAll) return ctx.docsAll;
951
+ const { repoRoot, config } = ctx;
952
+ const out = [];
953
+ const exists = existsSync(join(repoRoot, config.docsDir));
954
+ const stack = [config.docsDir];
955
+ while (exists && stack.length) {
956
+ const rel = stack.pop();
957
+ let entries;
958
+ try { entries = readdirSync(join(repoRoot, rel), { withFileTypes: true }); } catch { continue; }
959
+ for (const e of entries) {
960
+ const childRel = `${rel}/${e.name}`;
961
+ if (SKIP_DIR_RE.test(`/${childRel}/`)) continue;
962
+ if (e.isDirectory()) stack.push(childRel);
963
+ else if (e.isFile()) out.push(childRel.split(sep).join("/"));
964
+ }
965
+ }
966
+ const { files } = ctx.ignoreFilter(out.sort());
967
+ ctx.docsAll = { exists, files };
968
+ return ctx.docsAll;
969
+ }
970
+
971
+ // A file's size, as a receipt input: layout checks never read content.
972
+ function sizeOf(repoRoot, rel) {
973
+ try { return statSync(join(repoRoot, rel)).size; } catch { return 0; }
974
+ }
975
+
976
+ // Check 9 — the index. `docs/README.md` names every ROOT entry of docs/ (one
977
+ // line per entry — a link to it, or the name in backticks); entries below the
978
+ // root are reached through their own directory's README, which is check 2's
979
+ // business, not this one. No index at all is only a finding once docs/ has
980
+ // INDEX_MIN_ENTRIES root entries — the same threshold handbook-sync uses to
981
+ // offer templates/docs-README.md, so a two-file docs/ is never nagged.
982
+ const INDEX_MIN_ENTRIES = 3;
983
+ const INDEX_NAMES = ["README.md", "INDEX.md"];
984
+
985
+ function checkDocsIndex(ctx) {
986
+ const { repoRoot, config, findings } = ctx;
987
+ const receipt = makeReceipt();
988
+ const check = "9 docs-index";
989
+ const { exists, files } = docsAllFiles(ctx);
990
+ if (!exists) {
991
+ receipt.note = `${config.docsDir}/ does not exist — nothing to index`;
992
+ return { receipt };
993
+ }
994
+ const prefix = `${config.docsDir}/`;
995
+ const roots = [...new Set(files.map((f) => f.slice(prefix.length).split("/")[0]))].sort();
996
+ const indexName = INDEX_NAMES.find((n) => roots.includes(n));
997
+ const entries = roots.filter((r) => !INDEX_NAMES.includes(r));
998
+ for (const r of roots) receipt.add(`${prefix}${r}`, ""); // the root listing is what was read
999
+ if (!indexName) {
1000
+ if (entries.length >= INDEX_MIN_ENTRIES) {
1001
+ findings.warn(check, `${config.docsDir}/ has ${entries.length} root entries and no ${config.docsDir}/README.md — add an index, one line per root entry (templates/docs-README.md), with \`${config.docsDir}/README.md merge=union\` in .gitattributes`);
1002
+ }
1003
+ receipt.note = `${entries.length} root entr(y/ies), no index`;
1004
+ return { receipt };
1005
+ }
1006
+ const indexPath = `${prefix}${indexName}`;
1007
+ const text = readFileSafeText(join(repoRoot, indexPath)) ?? "";
1008
+ receipt.add(indexPath, text);
1009
+ const named = new Set();
1010
+ ANY_LINK_TARGET_RE.lastIndex = 0;
1011
+ let m;
1012
+ while ((m = ANY_LINK_TARGET_RE.exec(text))) {
1013
+ const raw = m[1];
1014
+ if (isExternalTarget(raw) || PLACEHOLDER_TARGET_RE.test(raw)) continue;
1015
+ named.add(resolveRepoPath(config.docsDir, raw).slice(prefix.length).split("/")[0]);
1016
+ }
1017
+ for (const t of text.matchAll(/`\.?\/?([^`/\s]+)\/?`/g)) named.add(t[1]);
1018
+ let missing = 0;
1019
+ for (const e of entries) {
1020
+ if (named.has(e)) continue;
1021
+ missing++;
1022
+ findings.warn(check, `${prefix}${e} is a root entry of ${config.docsDir}/ that ${indexPath} never names — add its line to the index`);
1023
+ }
1024
+ receipt.note = `${entries.length} root entr(y/ies) vs ${indexPath}, ${missing} not indexed`;
1025
+ return { receipt };
1026
+ }
1027
+
1028
+ // Check 10 — transient names. Plans, proposals, reports, audits and session
1029
+ // notes are the Issue's, not current truth's. The signal is the word as the
1030
+ // FIRST or LAST word of a name under docs/ (`plan.md`, `q3-report.md`,
1031
+ // `audit-2025.md`, `plans/`), after a leading issue number is dropped — never a
1032
+ // substring (`planning-model.md`, `airplane.md`), and never a middle word, so
1033
+ // an issue-keyed record whose TOPIC is a plan (`536-handoff-missing-plan-
1034
+ // rationale.md`, measured on this handbook's own docs/adr/) stays quiet. A
1035
+ // dated MARKDOWN name is check 5's (left alone, so one file never warns
1036
+ // twice); a dated name on any other file (`2026-03-01-shot.png`) is reported here.
1037
+ const TRANSIENT_WORDS = new Set(["plan", "plans", "proposal", "proposals", "report", "reports", "audit", "audits"]);
1038
+
1039
+ function transientWord(rel) {
1040
+ for (const seg of rel.split("/")) {
1041
+ const words = seg.replace(/\.[^.]*$/, "").toLowerCase().split(/[-_.]+/).filter(Boolean);
1042
+ while (words.length && /^\d+$/.test(words[0])) words.shift();
1043
+ for (const w of [words[0], words[words.length - 1]]) if (w && TRANSIENT_WORDS.has(w)) return w;
1044
+ }
1045
+ return null;
1046
+ }
1047
+
1048
+ function checkTransientNames(ctx) {
1049
+ const { repoRoot, config, findings } = ctx;
1050
+ const receipt = makeReceipt();
1051
+ const check = "10 transient-names";
1052
+ const { files } = docsAllFiles(ctx);
1053
+ const prefix = `${config.docsDir}/`;
1054
+ let flagged = 0;
1055
+ for (const f of files) {
1056
+ receipt.add(f, String(sizeOf(repoRoot, f)));
1057
+ const rel = f.slice(prefix.length);
1058
+ const word = transientWord(rel);
1059
+ if (word) {
1060
+ flagged++;
1061
+ findings.warn(check, `${f} is named as a ${word.replace(/s$/, "")} — plans, proposals, reports, audits and session notes go on the Issue, not in ${config.docsDir}/ (current truth)`);
1062
+ } else if (!/\.md$/i.test(f) && DATED_NAME_RE.test(rel)) {
1063
+ flagged++;
1064
+ findings.warn(check, `${f} has a dated name — the issue number is the only key under ${config.docsDir}/`);
1065
+ }
1066
+ }
1067
+ receipt.note = `${files.length} name(s) checked, ${flagged} transient`;
1068
+ return { receipt };
1069
+ }
1070
+
1071
+ // Check 11 — lower-kebab-case names. Every path segment below docs/ is
1072
+ // lower-case letters, digits and hyphens, with dot-separated extensions
1073
+ // (`gotchas.d`, `x.test.md`). Two exemptions: README.md (any case of the
1074
+ // extension), and ONE leading underscore, which marks a shared support folder
1075
+ // (`design/_assets/`) rather than content.
1076
+ const KEBAB_SEGMENT_RE = /^_?[a-z0-9]+(-[a-z0-9]+)*(\.[a-z0-9]+(-[a-z0-9]+)*)*$/;
1077
+
1078
+ function checkKebabNames(ctx) {
1079
+ const { repoRoot, config, findings } = ctx;
1080
+ const receipt = makeReceipt();
1081
+ const check = "11 kebab-names";
1082
+ const { files } = docsAllFiles(ctx);
1083
+ const prefix = `${config.docsDir}/`;
1084
+ const reported = new Set();
1085
+ for (const f of files) {
1086
+ receipt.add(f, String(sizeOf(repoRoot, f)));
1087
+ const segs = f.slice(prefix.length).split("/");
1088
+ for (let i = 0; i < segs.length; i++) {
1089
+ const seg = segs[i];
1090
+ const last = i === segs.length - 1;
1091
+ if (last && /^readme\.md$/i.test(seg)) continue;
1092
+ if (KEBAB_SEGMENT_RE.test(seg)) continue;
1093
+ const where = `${prefix}${segs.slice(0, i + 1).join("/")}${last ? "" : "/"}`;
1094
+ if (reported.has(where)) break; // one finding per offending directory, not one per file in it
1095
+ reported.add(where);
1096
+ findings.warn(check, `${where} is not lower-kebab-case — names under ${config.docsDir}/ are lower-case words joined by hyphens (README.md excepted)`);
1097
+ break;
1098
+ }
1099
+ }
1100
+ receipt.note = `${files.length} path(s) checked, ${reported.size} non-kebab name(s)`;
1101
+ return { receipt };
1102
+ }
1103
+
1104
+ // Check 12 — design artifacts live in one folder per design issue,
1105
+ // `design/<slug>-<N>/` (spec, mockup, frames/). Flagged: a loose file at the
1106
+ // design root (README.md, the folder's index, excepted) and a first-level
1107
+ // folder that is not `<slug>-<N>` — a bare number (`design/123/`) included —
1108
+ // apart from `_assets/`, the one shared copy of fonts and CSS. What sits
1109
+ // INSIDE a well-named folder is that folder's own business.
1110
+ const DESIGN_FOLDER_RE = /^[a-z0-9]+(-[a-z0-9]+)*-\d+$/;
1111
+
1112
+ function checkDesignLayout(ctx) {
1113
+ const { repoRoot, config, findings } = ctx;
1114
+ const receipt = makeReceipt();
1115
+ const check = "12 design-layout";
1116
+ const designDir = `${config.docsDir}/design`;
1117
+ const inDesign = docsAllFiles(ctx).files.filter((f) => f.startsWith(`${designDir}/`));
1118
+ if (inDesign.length === 0) {
1119
+ receipt.note = `${designDir}/ has no files — nothing to check`;
1120
+ return { receipt };
1121
+ }
1122
+ const badFolders = new Set();
1123
+ let loose = 0;
1124
+ for (const f of inDesign) {
1125
+ receipt.add(f, String(sizeOf(repoRoot, f)));
1126
+ const segs = f.slice(designDir.length + 1).split("/");
1127
+ if (segs.length === 1) {
1128
+ if (/^readme\.md$/i.test(segs[0])) continue;
1129
+ loose++;
1130
+ findings.warn(check, `${f} sits loose in ${designDir}/ — a design artifact belongs in ${designDir}/<slug>-<N>/ (a file already here may stay — lazy migration; new ones go in a folder)`);
1131
+ } else if (segs[0] !== "_assets" && !DESIGN_FOLDER_RE.test(segs[0]) && !badFolders.has(segs[0])) {
1132
+ badFolders.add(segs[0]);
1133
+ findings.warn(check, `${designDir}/${segs[0]}/ is not named <slug>-<N> — one folder per design issue, slug first, issue number last`);
1134
+ }
1135
+ }
1136
+ receipt.note = `${inDesign.length} file(s) under ${designDir}/, ${loose} loose, ${badFolders.size} misnamed folder(s)`;
1137
+ return { receipt };
1138
+ }
1139
+
1140
+ // Check 13 — image weight. An image over IMAGE_MAX_BYTES under docs/ is
1141
+ // weight every clone carries forever; export it smaller, or link it.
1142
+ const IMAGE_EXT_RE = /\.(png|jpe?g|gif|webp|avif|bmp|tiff?|svg|heic)$/i;
1143
+ const IMAGE_MAX_BYTES = 1024 * 1024;
1144
+
1145
+ function checkLargeImages(ctx) {
1146
+ const { repoRoot, config, findings } = ctx;
1147
+ const receipt = makeReceipt();
1148
+ const check = "13 large-images";
1149
+ const images = docsAllFiles(ctx).files.filter((f) => IMAGE_EXT_RE.test(f));
1150
+ let flagged = 0;
1151
+ for (const f of images) {
1152
+ const size = sizeOf(repoRoot, f);
1153
+ receipt.add(f, String(size));
1154
+ if (size > IMAGE_MAX_BYTES) {
1155
+ flagged++;
1156
+ findings.warn(check, `${f} is ${(size / 1024 / 1024).toFixed(1)} MB — over the 1 MB advisory ceiling for an image under ${config.docsDir}/; export it smaller`);
1157
+ }
1158
+ }
1159
+ receipt.note = `${images.length} image(s) checked, ${flagged} over 1 MB`;
1160
+ return { receipt };
1161
+ }
1162
+
1163
+ // Check 14 — fonts in design folders. A design folder links the design-system
1164
+ // package, or the one shared copy in `design/_assets/` — it never carries its
1165
+ // own fonts (measured: 454 font files for 11 unique ones, one repo).
1166
+ const FONT_EXT_RE = /\.(woff2?|ttf|otf|eot)$/i;
1167
+
1168
+ function checkDesignFonts(ctx) {
1169
+ const { repoRoot, config, findings } = ctx;
1170
+ const receipt = makeReceipt();
1171
+ const check = "14 design-fonts";
1172
+ const designDir = `${config.docsDir}/design`;
1173
+ const fonts = docsAllFiles(ctx).files.filter((f) => f.startsWith(`${designDir}/`) && FONT_EXT_RE.test(f));
1174
+ let flagged = 0;
1175
+ for (const f of fonts) {
1176
+ receipt.add(f, String(sizeOf(repoRoot, f)));
1177
+ if (f.startsWith(`${designDir}/_assets/`)) continue;
1178
+ flagged++;
1179
+ findings.warn(check, `${f} is a font copied into a design folder — link the design-system package, or keep one copy in ${designDir}/_assets/`);
1180
+ }
1181
+ receipt.note = `${fonts.length} font file(s) under ${designDir}/, ${flagged} outside _assets/`;
1182
+ return { receipt };
1183
+ }
1184
+
928
1185
  // ---------------------------------------------------------------------------
929
1186
  // Main
930
1187
  // ---------------------------------------------------------------------------
@@ -938,6 +1195,12 @@ const CHECKS = [
938
1195
  ["6 section-citations", checkGotchaCitations],
939
1196
  ["7 gotchas-d-registry", checkGotchasDRegistry],
940
1197
  ["8 two-surface-linkage", checkTwoSurfaceLinkage],
1198
+ ["9 docs-index", checkDocsIndex],
1199
+ ["10 transient-names", checkTransientNames],
1200
+ ["11 kebab-names", checkKebabNames],
1201
+ ["12 design-layout", checkDesignLayout],
1202
+ ["13 large-images", checkLargeImages],
1203
+ ["14 design-fonts", checkDesignFonts],
941
1204
  ];
942
1205
 
943
1206
  function main() {
@@ -85,6 +85,18 @@ env:
85
85
  # is no artifact lying around from the CI run on main. To use this you must add a
86
86
  # build job to THIS file that uploads an artifact, and make the release job
87
87
  # `needs:` it. Left false because most of our repos build on the deploy target.
88
+ #
89
+ # The files come through the organisation's artifact store, not GitHub's capped
90
+ # artifact allowance (CONVENTIONS.md §7, "CI artifacts", #601): the "Download build
91
+ # artifacts" step calls artifact-store/download, so your build job uploads with
92
+ # artifact-store/upload and the same five secrets — ARTIFACT_STORE_ENDPOINT,
93
+ # ARTIFACT_STORE_BUCKET, ARTIFACT_STORE_ACCESS_KEY, ARTIFACT_STORE_SECRET_KEY and
94
+ # ARTIFACT_STORE_REGION (docs/artifact-store.md in the handbook). Until the bucket
95
+ # secret exists the step runs with `backend: github`, i.e. GitHub's own artifact
96
+ # action, so a fresh copy works before its store does.
97
+ # ⚠ REGION: requests are signed for the region and default to us-east-1. A store
98
+ # configured with any other region answers 400 to every GET signed for the wrong one,
99
+ # so set ARTIFACT_STORE_REGION — on the upload call site too, not just this one.
88
100
  ATTACH_ARTIFACTS: "false"
89
101
  # Empty means every artifact from this run.
90
102
  ARTIFACT_NAME: ""
@@ -228,13 +240,26 @@ jobs:
228
240
  # Same summary into the run page, so it is readable without opening Releases.
229
241
  cat /tmp/body.md >> "$GITHUB_STEP_SUMMARY"
230
242
 
243
+ # Through the artifact store (#601): see ATTACH_ARTIFACTS above for the secrets and
244
+ # the region trap. EDIT: `@HANDBOOK_TAG` is the handbook release this copy calls —
245
+ # `colab template` writes the version it stamps; by hand, pin a tag or a commit, never
246
+ # a branch. Copied the action into this repo instead? `uses: ./.github/actions/artifact-store/download`.
231
247
  - name: Download build artifacts
232
248
  if: env.ATTACH_ARTIFACTS == 'true'
233
- uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
249
+ uses: futurelastic/colab-handbook/.github/actions/artifact-store/download@HANDBOOK_TAG
234
250
  with:
235
- # Empty name = every artifact produced by this run.
251
+ # Empty name = every artifact produced by this run, each in release-artifacts/<name>/.
236
252
  name: ${{ env.ARTIFACT_NAME }}
237
253
  path: release-artifacts
254
+ # No bucket secret yet → GitHub's own artifact action, unchanged. The bucket, not the
255
+ # endpoint, decides: an empty endpoint is a real store (the AWS default), a missing
256
+ # bucket is none.
257
+ backend: ${{ secrets.ARTIFACT_STORE_BUCKET != '' && 's3' || 'github' }}
258
+ endpoint: ${{ secrets.ARTIFACT_STORE_ENDPOINT }}
259
+ bucket: ${{ secrets.ARTIFACT_STORE_BUCKET }}
260
+ access-key: ${{ secrets.ARTIFACT_STORE_ACCESS_KEY }}
261
+ secret-key: ${{ secrets.ARTIFACT_STORE_SECRET_KEY }}
262
+ region: ${{ secrets.ARTIFACT_STORE_REGION }}
238
263
  continue-on-error: true
239
264
 
240
265
  - name: List artifacts to attach
@@ -76,8 +76,10 @@ function substituteTrunk(text, p) {
76
76
  * a refreshed file stays byte-identical to what `colab template <name> --force` would write.
77
77
  */
78
78
  function renderForRepo(name, body, doc, version) {
79
- if (!/^ci-/.test(String(name || ''))) return body;
79
+ // The pin applies to every template, as `colab template` writes it (#754: release-tag and dist-refs
80
+ // call the artifact-store action at `@HANDBOOK_TAG`); only the trunk refs are CI-template-only.
80
81
  const pinned = version ? pinHandbookTag(body, version).text : body;
82
+ if (!/^ci-/.test(String(name || ''))) return pinned;
81
83
  const p = protectedRefs(doc);
82
84
  return p ? substituteTrunk(pinned, p).text : pinned;
83
85
  }