@theholocron/cli 5.0.0-alpha.32 → 5.0.0-alpha.326

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/README.md CHANGED
@@ -17,39 +17,122 @@ holocron --help
17
17
  ## Interactive mode
18
18
 
19
19
  Run `holocron` with no command, a parent command with no subcommand
20
- (`holocron auth`, `holocron skills`, `holocron upgrade`), or a leaf command
21
- missing a required positional (`holocron deploy`, `holocron secret set`), and
22
- you get a prompt instead of a `--help` dead end:
20
+ (`holocron auth`, `holocron repo`, `holocron repo upgrade`, …), or a leaf command
21
+ missing a required positional (`holocron deploy`, `holocron secrets set`), and
22
+ you get a prompt instead of a `--help` dead end.
23
+
24
+ The menu mirrors the command tree: each level shows only the next word, and a
25
+ group (marked `›`) opens its own submenu, as deep as the commands nest. Nothing
26
+ is shown as a `<command> <subcommand>` path — `config show` is `config ›` then
27
+ `show`. Every submenu has a `← back` item, and a command that is also a group
28
+ (`repo sync`, `deploy`) has a `(run it)` item at the top of its submenu. Typing
29
+ searches the whole tree — `upgrade` at the top finds the `repo` group — with
30
+ name matches ranked above description matches.
31
+
32
+ ```console
33
+ $ holocron
34
+ ? What would you like to do? › repo
35
+ ❯ repo ›
36
+ ? repo — choose a subcommand: › upgrade
37
+ ? repo upgrade — choose a subcommand: › node
38
+ ? Target Node.js major version: › 24
39
+ ```
23
40
 
41
+ For a command that declares options (so far: `package publish` — more are
42
+ rolled out one command group at a time), it also offers those: any required
43
+ option is prompted like a positional, and everything else goes through one
44
+ "Set any options?" checkbox, prompting only what you picked:
45
+
46
+ ```console
47
+ ? Set any options? (space to select, enter to skip) › ◉ npm dist-tag ◯ One-time password (2FA)
48
+ ? npm dist-tag (blank = latest): › beta
24
49
  ```
25
- $ holocron
26
- ? What would you like to do? › dep
27
- ────────────────────────────────────────────────
28
- ❯ deploy Trigger a deployment via the configured `deployment` capability
29
50
 
30
- ? Branch to deploy: › main
51
+ `package publish` specifically has three workflows that don't mix — a
52
+ steady-state publish, a one-shot `--initial` bootstrap, and a `--sync-trust`
53
+ maintenance run — so it asks which one first, then only offers that
54
+ workflow's own options; nothing from a different workflow is ever shown:
55
+
56
+ ```console
57
+ ? What would you like to do? › Initial publish (--initial)
58
+ ? Set any options? (space to select, enter to skip) › ◉ One-time password (2FA)
59
+ ...dry-run output...
60
+ ? Dry run complete — proceed with the real run? › yes
61
+ ? One-time password (2FA), if npm requires it for this publish: › ***
31
62
  ```
32
63
 
64
+ Each workflow's label ends with its real flag in parentheses when it has
65
+ one, and a longer caveat ("use only for a package's very first publish")
66
+ shows as helper text under the highlighted choice rather than bloating the
67
+ label itself.
68
+
69
+ A secret option (`--otp`) is masked as you type and delivered to the spawned
70
+ command through its environment, never its argv — `ps` and shell history
71
+ both expose a child's argv, never its env. A time-sensitive one like `--otp`
72
+ is checked off early but not actually typed until right before the real run
73
+ — after the dry-run preview and the "proceed?" question, never before —
74
+ since a dry run never checks it anyway and a code typed any earlier risks
75
+ going stale while something else is still being answered.
76
+
77
+ Whether an option is _checkbox-optional vs. always included_ and _collected
78
+ upfront vs. collected last_ are independent choices. `package publish`'s
79
+ `--otp` is always collected last, but whether it's checkbox-optional depends
80
+ on `HOLOCRON_NPM_ENFORCE_2FA`: unset (the default), it's opt-in like any other
81
+ checkbox pick; set in your own shell profile (never checked into the repo),
82
+ it's always included — for an operator whose own npm account enforces 2FA
83
+ on every publish, so the box doesn't need re-checking every single run.
84
+ Setting it has no effect on anyone else publishing from the same repo.
85
+
33
86
  The picked command spawns as a normal `holocron <command> …` invocation —
34
87
  `--token`, `--org`, `--cwd`, and `--dry-run` on the original invocation carry
35
88
  through. A non-interactive shell (CI, a script, a pipe) gets the old
36
89
  hard-failure message instead of hanging on a prompt.
37
90
 
91
+ For a command whose handler honours `--dry-run` (most of them — everything
92
+ except `auth *` and `config show`), the menu always previews it first — a
93
+ dry run doesn't mutate anything, so there's nothing to ask permission for —
94
+ then asks the one real decision:
95
+
96
+ ```console
97
+ ...dry-run output...
98
+ ? Dry run complete — proceed with the real run? › yes
99
+ ```
100
+
101
+ A preview that reports nothing would actually change (e.g. `clone` finding
102
+ every repo already cloned) skips that question too — there'd be nothing for
103
+ the real run to do either. `--skip-dry-run` opts out of the preview
104
+ entirely, straight to the real run, for when you already know what you want.
105
+
38
106
  ## Execution contexts
39
107
 
40
108
  Every command is tagged with how much of a repo it needs:
41
109
 
42
- | Context | Needs | Examples |
43
- | ------------ | -------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
44
- | `global` | just the CLI binary | `version`, `clone`, `new`, `upgrade node`, `auth set` / `check`, `plugin create`, `skills …` |
45
- | `repo-aware` | `./holocron.config` in cwd, no plugins | `run`, `ci`, `config show`, `sync-readme` |
46
- | `workspace` | the `@theholocron/holocron-plugin-*` packages resolvable | `doctor`, `setup`, `sync`, `secrets sync`, `deploy` |
110
+ | Context | Needs | Examples |
111
+ | ------------ | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
112
+ | `global` | the CLI binary alone | `version`, `clone`, `new repo` / `plugin`, `repo upgrade …`, `auth set` / `check`, `package …`, `run lint commit-msg`, `skills …` |
113
+ | `repo-aware` | `./holocron.config`, walking up from cwd, no plugins | `run`, `run ci`, `config show`, `repo sync readme`, `deploy on-release` |
114
+ | `workspace` | the `@theholocron/holocron-plugin-*` packages resolvable | `doctor`, `repo setup`, `repo sync`, `repo cleanup branches`, `secrets …`, `deploy`, `sync github` |
47
115
 
48
116
  A `workspace` command run from a bare global install (no plugins next to the
49
117
  CLI) fails with one actionable line — install the plugins as devDependencies or
50
118
  use `pnpm exec holocron <cmd>`. `auth check` degrades to "token present,
51
119
  verification skipped" instead. `holocron --help` prints the grouping; see
52
- [Execution Contexts](https://theholocron.github.io/holocron/execution-contexts).
120
+ [Execution Contexts](https://docs.theholocron.dev/holocron/execution-contexts).
121
+
122
+ ### Viewing the resolved config
123
+
124
+ `holocron config show` prints the resolved config. On a TTY it opens a foldable
125
+ tree by default; piped or redirected, it always emits plain, valid JSON
126
+ (`holocron config show | jq`).
127
+
128
+ ```console
129
+ holocron config show # TTY: foldable tree (↑↓ move, →/⏎ expand, ← collapse, E/C all, q quit)
130
+ holocron config show --depth 2 # static coloured tree, anything nested deeper than 2 levels collapsed
131
+ holocron config show --no-interactive # static coloured tree, fully expanded
132
+ ```
133
+
134
+ Passing `--interactive` explicitly needs a TTY on stdin and stdout and fails
135
+ with a one-line message otherwise; the default falls back to static output. It has no extra dependencies — nothing to install.
53
136
 
54
137
  ## Config file
55
138
 
@@ -103,18 +186,20 @@ A minimal config — for repos with a `package.json` and a GitHub remote
103
186
 
104
187
  ### repo options
105
188
 
106
- Additional `repo` fields recognised by `holocron setup`:
189
+ Additional `repo` fields recognised by `holocron repo setup`:
107
190
 
108
- | Field | Type | Description |
109
- | ----------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
110
- | `repo.teams` | `Array<string \| { slug, permission }>` | GitHub teams granted repo access. String shorthand defaults to `push` (Write). `holocron setup` also writes `.github/CODEOWNERS` for teams with `push`/`maintain`/`admin`. |
111
- | `repo.topics` | `string[]` | GitHub topics set on the repository. |
112
- | `repo.protection` | `"balanced" \| "strict" \| "none"` | Branch-protection preset applied by `holocron setup`. For `"strict"`, the required status checks are derived from the task manifest — see below. |
113
- | `repo.properties` | `RepoProperties` | Org-level custom property values synced to the GitHub dashboard. |
191
+ | Field | Type | Description |
192
+ | ----------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
193
+ | `repo.teams` | `Array<string \| { slug, permission }>` | GitHub teams granted repo access. String shorthand defaults to `push` (Write). `holocron repo setup` also writes `.github/CODEOWNERS` for teams with `push`/`maintain`/`admin`. |
194
+ | `repo.topics` | `string[]` | GitHub topics set on the repository. |
195
+ | `repo.protection` | `"balanced" \| "strict" \| "none"` | Branch-protection preset applied by `holocron repo setup`. For `"strict"`, the required status checks are derived from the task manifest — see below. |
196
+ | `repo.properties` | `RepoProperties` | Org-level custom property values synced to the GitHub dashboard. |
197
+ | `repo.variables` | `{ repo?, org?, prune? }` | GitHub Actions variables created and updated by `holocron repo setup`. Undeclared ones are left alone unless `prune` is on. |
198
+ | `repo.secrets` | `{ repo?, org?, environments?, sync? }` | Names of the secrets that must exist, checked (never written) by `holocron doctor secrets`. Names only. The notification layout's secrets and a Chromatic project token are expected without being listed. `sync: [{ environment, keys?, scope? }]` declares the vault environments `secrets sync` fills from; the doctor expects their keys (every key the `vault` provider lists when `keys` is omitted, names only) at the `scope` (`repo`, `env=<name>`, `org=<name>`). |
114
199
 
115
200
  ### Custom properties synced to GitHub
116
201
 
117
- `holocron setup` and `holocron sync` both call `syncProperties()` with two
202
+ `holocron repo setup` and `holocron repo sync` both call `syncProperties()` with two
118
203
  kinds of fields — always one-way (`holocron.config.ts` → resolved →
119
204
  properties; properties are never a second editable source of truth):
120
205
 
@@ -139,7 +224,7 @@ properties; properties are never a second editable source of truth):
139
224
  | `holocron_compliance` | `"compliant" \| "non-compliant"` against a minimal `source` + `ci` baseline |
140
225
 
141
226
  Field definitions and derivation heuristics:
142
- `.notes/tech-holocron-platform.spec.md` → "Custom-properties sync — field
227
+ `docs/wiki/specifications/tech-holocron-platform.spec.md` → "Custom-properties sync — field
143
228
  definitions (#677)".
144
229
 
145
230
  The four derived fields' pure computation —
@@ -160,20 +245,27 @@ posts, instead of reporting pass/fail.
160
245
 
161
246
  ### Required status checks (`protection: "strict"`)
162
247
 
163
- `holocron setup` builds the branch-protection required-check list from the
248
+ `holocron repo setup` builds the branch-protection required-check list from the
164
249
  manifest, not a hand-maintained array:
165
250
 
166
- - `"DCO"` (hard-prepended), then
251
+ In the repo that hosts the reusable workflows (holocron itself) the list is `ci / Required checks` and `DCO`. That is the aggregate
252
+ check (`ci/workflows/ci.yml`, written by `repo setup` / `repo sync` as `.github/workflows/ci.ci.yml`): it waits on
253
+ every `{ required: true }` task, the hand-written checks in `extraRequiredChecks` and its `codecov/*` statuses, and its
254
+ job summary lists each of them with a link, failing ones first. `DCO` stays its own required context. In any other
255
+ repo, which has no `ci` caller yet, the list is:
256
+
257
+ - `"DCO"`, then
167
258
  - every `{ required: true }` task's workflow check context (`Lint / Conclusion`,
168
- `Test / Conclusion`, `Typecheck / Conclusion`, `audit / Conclusion`), walked
259
+ `Test / Conclusion`, `Typecheck / Conclusion` while the repo is on the frozen reusables; `test:unit / Conclusion`,
260
+ `typecheck / Run tsc --noEmit`, … once it moves to the flat ones), walked
169
261
  in CI order, then
170
262
  - the top-level `extraRequiredChecks` (codecov gates, a bundle-build check, …).
171
263
 
172
264
  ```ts
173
265
  export default defineConfig({
174
266
  tasks: [
175
- { name: "lint", required: true },
176
- { name: "test", required: true },
267
+ { name: "lint:code", required: true },
268
+ { name: "test:unit", required: true },
177
269
  { name: "typecheck", required: true },
178
270
  ],
179
271
  extraRequiredChecks: ["codecov/patch", "codecov/project"],
@@ -186,11 +278,45 @@ The generated ruleset also sets `require_extra_approval_for_unattributed_changes
186
278
  false` — with `required_approving_review_count: 0` and a single maintainer, the
187
279
  GitHub default (`true`) is an unsatisfiable block on any PR with an
188
280
  unverified/unattributed commit. Repository-admin bypass still covers the real
189
- risk. And the `codecov.yml` `holocron setup` writes carries `if_not_found:
281
+ risk. And the `codecov.yml` `holocron repo setup` writes carries `if_not_found:
190
282
  success` on every status default, so an infra-only PR (dep bump, config,
191
283
  lockfile — no coverable change) passes instead of hanging on a `codecov/*`
192
- required check that never posts. A re-run of `holocron setup` backfills both into
193
- an existing repo.
284
+ required check that never posts. It also ignores `**/*.mdx`, so a docs-only PR that
285
+ adds pages is not judged to change testable files and left with an empty upload.
286
+ A re-run of `holocron repo setup` backfills all of these into an existing repo.
287
+
288
+ ### Default branch (`repo.defaultBranch`)
289
+
290
+ ```ts
291
+ export default defineConfig({
292
+ repo: { protection: "strict", defaultBranch: "alpha" },
293
+ providers: { source: "github" },
294
+ });
295
+ ```
296
+
297
+ `holocron repo setup` syncs GitHub's repo-level default branch (`HEAD`) — what a
298
+ fresh clone checks out, what `gh pr create`/the compare UI target by default,
299
+ and what Sentinel's `validateConfig()` reads (it only ever reads config from
300
+ the repo's default branch, never a PR ref — a deliberate security boundary).
301
+ Omit this field to leave GitHub's current setting untouched; most repos never
302
+ need it. It exists for a repo using a `main`/`alpha` prerelease-channel split
303
+ where active development happens on a non-`main` branch: set this to that
304
+ branch so Sentinel validates against what's actually being developed, then
305
+ change it back once that branch merges to `main` for a stable cut and stops
306
+ being the active branch.
307
+
308
+ ### Doc-comment coverage
309
+
310
+ ```ts
311
+ export default defineConfig({
312
+ repoValidation: { docsCoverage: "required" }, // "off" (default) | "warn" | "required"
313
+ });
314
+ ```
315
+
316
+ Controls `holocron probe docs patch` (skipped, reports without failing, or fails for an export a PR adds or changes
317
+ without a doc comment) and whether `holocron repo setup` adds the `documentation` flag and its statuses to
318
+ `codecov.yml`, informational for `"warn"`. It never touches the required checks. See the
319
+ [config docs](https://docs.theholocron.dev/holocron/config/#doc-comment-coverage).
194
320
 
195
321
  ### Git hooks
196
322
 
@@ -202,7 +328,7 @@ export default defineConfig({
202
328
  });
203
329
  ```
204
330
 
205
- `holocron setup` writes `.husky/pre-push` (runs `holocron ci` before every
331
+ `holocron repo setup` writes `.husky/pre-push` (runs `holocron run ci` before every
206
332
  push) and `.husky/pre-commit` (runs `gitleaks protect --staged` + `lint-staged`
207
333
  before every commit — scoped to staged changes, not the whole history, so a
208
334
  past false positive can't permanently block future commits) and sets
@@ -213,20 +339,22 @@ setup --hooks` / `--no-hooks` override per run. Bypass one push with `git push
213
339
 
214
340
  ### Task scripts
215
341
 
216
- `holocron sync` reconciles `package.json#scripts` from the `tasks` manifest
342
+ `holocron repo sync` reconciles `package.json#scripts` from the `tasks` manifest
217
343
  (merge, never clobber — only the managed keys are touched):
218
344
 
219
345
  ```ts
220
346
  export default defineConfig({
221
- tasks: ["test", "lint", "typecheck"],
347
+ tasks: ["test:unit", "lint:code", "typecheck"],
222
348
  // syncScripts: false, // disable the step
223
- // holocronScript: "node packages/cli/dist/cli.mjs", // override the "holocron" entry
349
+ // holocronScript: "node cli/cli/dist/cli.mjs", // override the "holocron" entry
224
350
  providers: { source: "github" },
225
351
  });
226
352
  ```
227
353
 
228
- Writes `"holocron": "<holocronScript ?? 'holocron'>"` plus one
229
- `"<task>": "holocron run <task>"` per runnable task. `syncScripts: false`
354
+ Writes `"holocron": "<holocronScript ?? 'holocron'>"` plus one script per runnable task, named by the task id
355
+ (`test:unit`) and one per suite (`test`, `lint`, `scan`): `turbo run <task>` in a pnpm workspace with a `turbo.json`
356
+ (or the tool's own command for a task that runs once at the root), `holocron run <task> --` in a single package.
357
+ `holocron probe generated check` fails on a root script that differs from what is generated. `syncScripts: false`
230
358
  opts out entirely.
231
359
 
232
360
  ### Splitting the task manifest — `astromech.config.ts`
@@ -240,7 +368,7 @@ The `tasks` key (plus `syncScripts` / `holocronScript` / `hooks` /
240
368
  import { defineConfig } from "@theholocron/astromech/config";
241
369
 
242
370
  export default defineConfig({
243
- tasks: [{ name: "audit", required: true, with: { "run-knip": true } }, "wiki"],
371
+ tasks: [{ name: "lint:unused", required: true }, "publish-wiki"],
244
372
  syncScripts: false,
245
373
  });
246
374
  ```
@@ -248,38 +376,56 @@ export default defineConfig({
248
376
  `@theholocron/astromech`'s `loadTasksConfig` merges it over
249
377
  `holocron.config`'s `tasks` — **task arrays concatenate**
250
378
  (`holocron.config` first), the dedicated file **wins on scalars**,
251
- `extraRequiredChecks` concatenate. `holocron run` / `holocron ci` /
252
- `holocron setup` / `holocron sync` all read the merged result, so the
379
+ `extraRequiredChecks` concatenate. `holocron run` / `holocron run ci` /
380
+ `holocron repo setup` / `holocron repo sync` all read the merged result, so the
253
381
  split is transparent. Useful for keeping the capability/provider config
254
382
  and the "what this repo runs" manifest in separate files (this repo does).
255
383
 
256
384
  ### `holocron run`
257
385
 
258
386
  ```bash
259
- holocron run <task> [job] [--required] [--filter <pkg>] [--dry-run] [-- <passthrough>]
387
+ holocron run <task | suite> [qualifier | job] [--check] [--required] [--filter <pkg>] [--dry-run] [-- <passthrough>]
260
388
  ```
261
389
 
262
- Runs one task locally — resolving turbo vs the package manager vs the tool
263
- itself. A `job` argument targets a sub-job of tasks that have them: `holocron
264
- run audit performance` runs Lighthouse CI, `holocron run audit knip` runs Knip,
265
- `holocron run audit` (no job) runs every audit sub-job in declared order. A
266
- sub-job whose tool isn't installed, or that has no local equivalent
267
- (`bundle-size`), is skipped with a note — `--required` makes that a failure. For
268
- a task with no sub-jobs the `job` slot is the first passthrough arg
269
- (`holocron run build src/`).
270
-
271
- **CI runs the identical command.** The reusable `typecheck` / `test` / `audit`
272
- workflows call the `holocron` composite action
390
+ Runs one task, or a suite, locally — resolving turbo vs the package manager vs the tool
391
+ itself. Ids are flat and verb-first: `typecheck`, `build`, `test:unit`, `lint:code`.
392
+ `holocron run test` runs the `test` suite (every `test:*` leaf the repo lists, in registry order, each reported),
393
+ `holocron run test unit` and `holocron run test:unit` run one leaf. The words are joined with `:` and the longest match
394
+ wins, so `deploy preview` is `deploy-preview`; the rest is the `job` argument. A `job` targets a sub-job of the tasks
395
+ that have them (`holocron run lint commit-msg <file>`). A leaf whose tool isn't installed, or that has no local
396
+ equivalent, is skipped with a note — `--required` makes that a failure. For a task with no sub-jobs the `job` slot is the first passthrough arg
397
+ (`holocron run build src/`). `holocron run format` writes (prettier), `holocron run format --check` is read-only.
398
+ `holocron run --help` lists the tasks grouped under the six intent groups. The old dotted names
399
+ (`verification.unitTests`, `sourceQuality.formatting`, …) still work and print a deprecation notice on stderr. <!-- holocron-allow-old-name -->
400
+
401
+ **CI runs the identical command.** The reusable workflows (`typecheck`, `test-unit`,
402
+ `lint-code`, …) call the `holocron` composite action
273
403
  (`theholocron/.github/.github/actions/holocron@main`), whose body is
274
- `holocron run <task> [job]`. So `holocron run test` locally and the `Test` CI
404
+ `holocron run <task> [job]`. So `holocron run test:unit` locally and the `test:unit` CI
275
405
  job execute the same thing — at a turbo root both are
276
- `turbo run test -- --coverage` (the registry's org-default flags flow through
277
- turbo's `--`).
406
+ `turbo run <task>`. `test:unit` always runs with coverage (`vitest run --coverage`); there is no `--coverage` flag.
407
+
408
+ ### `holocron deploy on-release`
409
+
410
+ ```bash
411
+ holocron deploy on-release [--channel <alpha|main>] [--from <commit>] [--to <commit>] [--dry-run]
412
+ ```
278
413
 
279
- ### `holocron ci`
414
+ Deploys every workspace package whose own `holocron.config` declares
415
+ `{ name: "deploy", with: { on: "release" } }` (holocron#930), when the
416
+ release (`--channel`: its prerelease identifier, or `main`/empty for a stable
417
+ release) is on the task's `channel` (default `main`, the stable release) and changes the package or one of its
418
+ `workspace:*` dependencies between `--from` (the previous release's commit,
419
+ omitted when there is none) and `--to` (default `HEAD`). It waits for npm to
420
+ serve the release's new dependency versions, then runs `pnpm --filter <pkg>
421
+ deploy`. A package that doesn't apply is skipped; a deploy that
422
+ doesn't succeed exits non-zero. The shared `release` workflow runs it as its own
423
+ `deploy` job after the release job (opt in with `deploy-on-release: true`).
424
+
425
+ ### `holocron run ci`
280
426
 
281
427
  ```bash
282
- holocron ci [--all] [--filter <pkg>] [--dry-run]
428
+ holocron run ci [--all] [--filter <pkg>] [--dry-run]
283
429
  ```
284
430
 
285
431
  Runs the merge-gating checks locally, in CI order, exiting non-zero on the
@@ -288,29 +434,53 @@ first failure — the "will my PR be green?" pre-flight, and what the
288
434
  (falling back to every `ci: true` task when nothing is marked required).
289
435
  `--all` forces the full set; `--filter` is a `turbo --filter=` passthrough.
290
436
  Order comes from the `CI_ORDER` constant in `@theholocron/astromech`
291
- (`typecheck → lint → test → build → …`). Tasks with no local equivalent
292
- (`codeql`, `deploy`) are reported as enforced-in-CI, never failures; `audit`
293
- expands into its sub-jobs (each under its own `audit / …` check context)
294
- unless the repo ships its own `"audit"` script.
295
-
296
- ### Lint parity
297
-
298
- The `lint` task takes an optional `linters` array — one list that drives
299
- **both** the CI `lint` job (super-linter's `VALIDATE_*` env, baked into the
300
- generated `.github/workflows/lint.yml` thin caller as a `super-linter-env`
301
- input) **and** `holocron run lint` locally. Omitted → auto-detected from the
302
- config files present plus the org always-on set.
437
+ (`typecheck → lint:code → … → test:unit → build → …`). Tasks with no local equivalent
438
+ (`scan:code`, `deploy`) are reported as enforced-in-CI, never failures. `format` runs in its
439
+ read-only `--check` form.
440
+
441
+ ### `holocron deploy`
442
+
443
+ `holocron deploy <branch>` (a Git-linked deployment) and `holocron deploy
444
+ --files <dir>` (a directory of build output, no linked repo) both trigger a
445
+ deployment through the configured `deployment` capability, then **wait for
446
+ it to finish**. The command reports success, exit code 0, only when the
447
+ deployment reaches `ready`. A deployment that ends `error` or `cancelled`,
448
+ or is still building after 10 minutes, is a failure: the exit code is
449
+ non-zero and the output includes the provider's own reason
450
+ (`DeploymentRecord.errorMessage`, e.g. Vercel's `Command "npm install"
451
+ exited with 1`). Providers build asynchronously, so accepting a deployment
452
+ isn't the same as it going live (holocron#911).
453
+
454
+ Provider plugins support this through the `Deployment` capability's
455
+ existing `getDeployment(id)`. They should set `errorMessage` on the
456
+ returned `DeploymentRecord` whenever the provider exposes one.
457
+
458
+ ### `holocron monitoring check <url>`
459
+
460
+ Runs every configured `monitoring` check against `<url>` instead of each
461
+ check's own configured `url` — no vendor API call, only a plain HTTP
462
+ request evaluated locally against the exact same `assertions` already in
463
+ `holocron.config.ts`. Built for CI: the `check-preview` task runs
464
+ this against a PR's Vercel preview deployment (triggered by
465
+ `deployment_status`, not `push`/`pull_request`), reusing the production
466
+ check definitions to catch a breaking change before merge instead of
467
+ after (holocron#1010).
303
468
 
304
469
  ```ts
305
470
  export default defineConfig({
306
- tasks: [{ name: "lint", linters: ["eslint", "prettier", "yamllint", "actionlint", "gitleaks"] }],
307
- providers: { source: "github" },
471
+ tasks: ["check-preview"],
472
+ providers: {
473
+ monitoring: ["checkly", { accountId: "...", checks: [/* ... */] }],
474
+ },
308
475
  });
309
476
  ```
310
477
 
478
+ Exits non-zero if any check fails — the job's own pass/fail is what
479
+ posts as the GitHub check, no separate reporting step needed.
480
+
311
481
  ### Skills installer
312
482
 
313
- `holocron setup` can install shared skills from `@theholocron/skills` into the local repo:
483
+ `holocron repo setup` can install shared skills from `@theholocron/skills` into the local repo:
314
484
 
315
485
  ```ts
316
486
  export default defineConfig({
@@ -371,18 +541,101 @@ export default acmeConfig;
371
541
 
372
542
  ```
373
543
 
544
+ ## Notifications — server as code
545
+
546
+ A `notifications` provider can declare a whole server in `holocron.config.ts`
547
+ (`layout`: categories, channels, roles, access, server settings, welcome screen,
548
+ pinned messages, onboarding, the bot application) and the CLI applies and checks it. The
549
+ commands and the config are provider-neutral; Discord is the first provider.
550
+
551
+ | Command | What it does |
552
+ | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
553
+ | `holocron notifications setup` | Applies the layout; looks everything up by name first, so a re-run changes nothing that matches |
554
+ | `holocron notifications channel add <name>` | Creates one channel (optionally with a webhook whose URL is stored as a secret) |
555
+ | `holocron notifications create-server --name <n> --owner <id>` | Creates the server the layout describes, writes its id into the config, applies the layout, invites the owner, waits for them to join and hands the server over (`--resume` finishes an interrupted hand-over; `--force` allows a second server) |
556
+ | `holocron notifications link` | Links your account on the provider to your GitHub account by signing in with the provider (OAuth, nothing secret kept) |
557
+ | `holocron notifications sync-roles` | Makes who holds a role match a GitHub team, through the links file (`--keep` only adds; `--provider` picks one) |
558
+ | `holocron doctor notifications [--built-only] [--deliver] [--post]` | Step by step: does the server match the layout, do the secrets exist, and does a person (not the bot) own it. A full run also leaves one `🧪 test:` post in the layout's `testChannel`; `--built-only` posts nothing; `--deliver` posts to every channel and removes each post; `--post [channel]` posts the result as the bot (the failures, or only the summary when none failed). It also reads the Checkly feed (webhook, alert channel, subscriptions), the Comlink relay (Worker, route, bindings, the tracker's integration and rule) and the Notifications workflow (the file, and the secrets it reads), posting nothing, so `--built-only` keeps those steps |
559
+ | `holocron doctor variables` | Do the Actions variables `repo.variables` declares exist, with those values (and, for the organization's, that visibility)? One row for the repository and one for the organization, each only when declared. Read-only. An undeclared variable counts only with `prune`; a scope that cannot be read (no provider, no org token) is a skip, not a failure |
560
+ | `holocron doctor ci` | Has the repo moved to the flat task vocabulary? One row each for the `tasks:` entries (a deprecated alias, with the id that replaces it), the generated callers (file, workflow and job name equal the task id), the `ci` aggregate's `expected` list (no id missing or stale) and where the callers point (`theholocron/.github` or holocron `ci-v1`). Read-only, no provider needed; exits 1 on a failure. The ruleset's checks are `doctor repo`'s |
561
+ | `holocron doctor environments` | Do the deployment environments exist? The ones `repo setup` creates (`staging`, `production`, when an `environments` provider is configured) plus every environment `repo.secrets.environments` names. One row. A missing one fails; an extra one is never a problem; no provider with some named is a skip |
562
+ | `holocron doctor credentials` | Does the credentials environment exist, and does it hold every variable the configured plugins take? One row per variable and provider (`ok`, `fail` when missing, `skip` for an optional one not set), listing names only: it never reads a value, and says which spelling of the environment's name matched. |
563
+ | `holocron doctor repo` | Do the repository settings `repo setup` writes match the config? One row per group the config declares: description and homepage, default branch and merge settings, topics, custom properties, team access, branch protection; labels and security settings are always checked. Read-only. Reads through optional `Source` methods (`getRepoInfo`, `getProperties`, `listLabels`, `listTeamAccess`, `getRulesetDetail`, `getSecurity`); a group that cannot be read is a skip, not a failure |
564
+ | `holocron doctor dns` | Do the DNS records the config makes setup write exist, pointing where they should? The preview domain's apex and wildcard CNAMEs (Cloudflare), the docs host a wiki provider asks for, and the relay Worker's proxied placeholder; one row per zone. A missing record, another target or a missing proxy fails; an extra record never does. A record `ensureCustomDomain()` returns is not checked, because asking for it creates the domain |
565
+ | `holocron doctor monitoring` | Do the checks the `monitoring` provider declares exist in its account, matched by name, with the URL, method and (when stated) frequency, locations, activated, should-fail, body and assertions the config sets? One row. A check in the account that is not declared is never a problem. A provider that cannot list its checks, failed to load or has no token is a skip |
566
+ | `holocron doctor secrets` | Do the secrets the config says must exist (`repo.secrets`, plus the notification layout's webhook and role secrets and the Chromatic token) exist? One row for the repository, the organization and each environment, each only when something is expected there. Names only; an undeclared secret is never a problem. A scope that cannot be read is a skip |
567
+ | `holocron doctor tokens` | For every token a configured plugin lists (every plugin that resolves one: GitHub's nine, Discord's three, Sentry's two, ...), looked up as the plugin does (its env var, the vendor's, then keyring) and verified with its `verifyToken`: set and accepted is ok (with how long is left, when the token expires), set and rejected fails, a token with 7 days or fewer left fails with `expires in N days: renew it`, not set is a skip. No token is printed. What a token may do is not checked, because GitHub does not return a fine-grained token's permissions |
568
+ | `holocron doctor --all` | Runs every deep check (`doctor notifications`, `doctor variables`, ...) and prints one row each, then `N ok, N fail, N skipped` counted in checks. Exits 1 when any check failed. A check that cannot run (no provider, no token) is a skip with the reason. Read-only: notifications runs as `--built-only`, so it posts nothing |
569
+ | `holocron probe [<provider> [<probe>]] [--dry-run] [--yes] [--lcov <path>]` | Poke a live provider on purpose: list the probes, inspect something, or run a proof that cleans up after itself. Plugins offer the probes; nothing secret is printed; one that changes things asks first |
570
+
571
+ Channels fed by another service are declared with `feeds` on the channel: `{ name: "uptime", webhook: true, feeds: { monitoring: true } }` (the object form `{ name?, webhook?, avatar?, alerts? }` overrides the alert channel's name, default `Message to #<channel>`, the dedicated webhook's name, default the provider's, and gives that webhook a picture, a file path or `https://` URL, or `{ url, image }` (the URL is tried first, the file in the repo is the fallback), else the provider's own icon (`Monitoring.icon`, a URL and an embedded `data:` image; Checkly provides one), else the layout's `webhookAvatar`). A channel's own `webhook.avatar` and the layout's `webhookAvatar` take the same forms, a path or `https://` URL, or `{ url, image }` (the URL first, the file in the repo as the fallback); a relative path is read from the repository root. `setup` gives the channel a dedicated webhook and hands its URL straight to the `monitoring` provider through `Monitoring.ensureAlertChannel({ name, format: "discord", url? })`, which finds an alert channel of that name or creates one and subscribes every check; the URL is never stored as a secret. It needs a `monitoring` provider that implements `ensureAlertChannel` (Checkly does). `alerts: { failure?, recovery?, degraded?, sslExpiry?, sslExpiryThreshold? }` (`MonitoringAlertSettings`, passed as `ensureAlertChannel({ ..., alerts })`) sets what the alert channel alerts about: a new channel defaults to failure, recovery and degraded on and `sslExpiry` off, and on an existing channel a setting left out is left alone. A check in the `monitoring` provider's `checks` can route itself with `alertChannels: ["Message to #uptime"]` (`MonitoringCheckInput.alertChannels`, the alert channel names): it is then subscribed to those channels only, and a name no feed declares is refused by `setup`. `inspectAlertChannel` returns the channel's `alerts` and the `misrouted` checks that `doctor notifications` reports. Two feeds may not share an alert channel name, and a feed's webhook may not share the channel's own webhook name (compared without regard to case).
572
+
573
+ Channels fed by the error tracker add `feeds: { errors: true }` and a layout `relay: { host, zone?, script?, code? }`: `setup` makes a dedicated webhook, points `host` at the Comlink Worker (a proxied DNS record via `dns`), and deploys it via `workers.deployScript` with the webhook URL as `COMLINK_<SOURCE>_WEBHOOK`. The URL never leaves the Worker's secret; other secrets on the script are kept. With `relay.errors: { projects, integration?, rule?, frequency? }` it also ensures the tracker's integration and alert rule (`errors.ensureRelay`) and deploys the Worker with the integration's signing secret. Needs `errors`, `workers` and `dns`; only one channel may be fed.
574
+
575
+ `holocron secrets sync <env> --worker <script>` also sets every key of the vault environment on a deployed Worker as a secret, through the optional `Workers.setSecret(script, name, value)` (write-only; the Cloudflare plugin implements it). The Worker must already exist. Sync only adds and updates: it never removes a binding, because a Worker also holds secrets that are not in the vault (for Comlink, the `COMLINK_<SOURCE>_WEBHOOK` that `notifications setup` sets), so a key deleted from the vault must be deleted from the Worker separately. Keys are written one at a time and each is reported; if one fails, the exit code is 1 and re-running finishes the rest, since every write is idempotent.
576
+
577
+ `holocron secrets list [--scope repo|environment|organization] [--env <name>] [--json]` prints the names (never the values; GitHub does not return them) of the secrets at each scope, sorted, under a heading per scope. With no `--scope` it lists the repository, plus the organization (`--org`, `HOLOCRON_ORG` or the config's `org`) and the `--env` environment when they are known; `--scope` lists one. A scope that cannot be listed is reported under its heading and the rest are still listed; the exit code is 1 if any failed. `--json` prints `[{ scope, names, error? }]`. It is read-only, so `--dry-run` does not apply. Comparing the names with what the config expects is `doctor secrets`, which also covers the keys of the vault environments declared in `repo.secrets.sync`.
578
+
579
+ A channel with `kind: "forum"` is a forum, with `tags` (each a `name`, an `emoji` and whether it is `moderated`); `setup` adds and corrects the tags but never removes one, and a text channel of the same name must be deleted first, since neither kind can become the other. A forum takes no `webhook` or `feeds`.
580
+
581
+ `holocron specs sync [--channel <forum>] [--files <paths...>] [--pr <number>] [--refresh] [--refresh-origin] [--refresh-titles] [--withdraw] [--notify]` keeps one forum post per ADR and spec in step with the files: it makes the post (titled with the document's own title, tagged with the file's status), writes its address into the file as `discussion.url`, and turns a gatekeeper's retag into an edit of the file's `status:` line in the working tree for a pull request. `--files` syncs only those files and `--pr` names a pull request on their posts, for a pull request that is still open. `--refresh-origin` is a one-off repair: it rewrites the `PR:` line of existing posts to the one the current rule names (the optional `prLine` of `DiscussionPatch`, and of `DiscussionPost`), and nothing else in them. `--refresh-titles` is the same kind of one-off repair for the title: it renames each existing post whose title differs from the current rule's (the optional `title` of `DiscussionPatch`, and of `DiscussionPost`) and changes nothing else; a rate limit stops it cleanly, reports how many documents are left, and the next run continues. The id that opens a post is a link to the file on the default branch (`repo.defaultBranch`, else `HEAD`) once the file is there, and plain text while `--pr` names an open pull request; the normal sync rewrites a post's id line (and only that line) whenever it is not the one the rule gives and no `--pr` is given, which covers a file that moved and a post made while its pull request was open, so it needs no extra request when every post is right and `--refresh` is no longer needed for it. `--refresh` runs the `PR:`, title and id-link repairs in one pass (the id link is the optional `idLine` of `DiscussionPatch`, and of `DiscussionPost`, which changes only the message's first line); `--refresh-origin` and `--refresh-titles` still do only their own. `--withdraw` (with `--files`, on the base branch) tags the posts of a pull request closed unmerged `withdrawn` and closes them; `withdrawn` is a tag only, never a file `status:`, and the next sync puts the file's own status back. It cannot be combined with `--refresh`, `--refresh-origin` or `--refresh-titles`. `--dry-run` previews it. See the [`specs sync` page](https://docs.theholocron.dev/holocron/commands/specs-sync/).
582
+
583
+ Pinned messages are declared under the provider's `layout` as `pinned: [{ channel, content }]` or `pinned: [{ channel, file }]` (`channel` is a channel in the layout, `content` up to 2000 characters, `file` a text file in the repository, such as `RULES.md`, whose contents are the message and win over a hand edit; `doctor notifications` reports the drift); the layout is the whole set of messages the bot has pinned in those channels.
584
+
585
+ Config shape added for role sync and sign-in (all under the provider's `layout`):
586
+
587
+ | Field | Meaning |
588
+ | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
589
+ | `testChannel` | The channel (it must declare a webhook) the doctor posts its one self-removing test message to. |
590
+ | `roles[].team` | A GitHub team slug. The role follows that team: given to linked members, taken from linked people who left. Never touches holders nobody has linked. |
591
+ | `links.hostedUrl` | A hosted sign-in service (Sentinel). `link` asks `<hostedUrl>/api/link` and uses it when it answers `{ "service": "link" }`; otherwise it signs in locally. |
592
+ | `links.localPort` | The port of the local sign-in listener (default `53682`, bound to `127.0.0.1` only). |
593
+ | `links.repo` / `links.path` | Where the links file lives (default `<org>/.github-private` and `notifications/<provider>-links.json`). |
594
+ | `application.intents.members` | Switches the Server Members Intent on or off (needed to list who holds a role). |
595
+ | `application.redirectUris` | Redirect URIs that must be registered. Check-only: the API cannot set them, so `setup` and the doctor say what to add in the developer portal. |
596
+
597
+ The links file is `{ "version": 1, "links": [{ "github": "<id>", "login": "<login>", "member": "<id>" }] }`: two public ids per person.
598
+ It is read and written through the `source` capability with the `github.user-sync` token (fine-grained, **only** the
599
+ private config repo, Contents read and write), so no other token needs Contents on other repositories.
600
+
601
+ Capability surface behind it (all optional, so providers without the concept omit them):
602
+
603
+ - `Source.teamMembers(teamSlug, org?)`, `Source.readFile(path, repo?)` (returns the `version` a later write must present),
604
+ `Source.writeFile(path, content, { message, version?, repo? })` (a changed `version` is refused: a real conflict check).
605
+ - `Notifications.createServer({ name, force? })`, `inviteLink(channel)`, `hasMember(id)`, `transferServer(id)` and `serverOwner()`: create a server, invite its owner, check they joined, hand it over, and say who owns it.
606
+ - `Notifications.roleMembers(role)`, `addRoleMember(role, memberId)`, `removeRoleMember(role, memberId)`.
607
+ - `Notifications.checkDelivery({ channel, name, category?, text })`: posts through a channel's webhook, reads the post back and removes it, and says which step failed.
608
+ - `Notifications.signIn()` returning `{ authorizeUrl, complete }`: the provider-neutral shape of "prove which account you own".
609
+ - `Notifications.ensureApplication` returns `{ updated, todo? }`; each `todo` is a step only a person can do (a portal setting
610
+ the API ignores) and is reported as a failure until done.
611
+
612
+ Provider credentials for Discord: `discord.holonet` is the **bot token** (Bot → Reset Token), `discord.holonet.oauth` is the
613
+ **OAuth client secret** (OAuth2 → Reset Secret). They are different values; the API can create or read neither.
614
+
615
+ See the [command pages](https://theholocron.dev/holocron/commands/notifications-setup/) for each command's options.
616
+
617
+ ## Cleaning up
618
+
619
+ - **`holocron repo cleanup branches [--local | --remote]`** — lists the branches whose pull request is merged,
620
+ grouped, each saying whether it lives locally, on the remote or both; then asks, and offers a checklist with the
621
+ proven-merged ones ticked. Proven merged means an ancestor of `origin/alpha` or `origin/main`, or the head (or an
622
+ ancestor, or one of the commits) of a merged pull request. Branches with more commits than their merged PR, with
623
+ an open PR, checked out (here or in a worktree), or never merged are listed unticked. `--dry-run` only lists;
624
+ `--yes` deletes every proven-merged branch without asking. Pull requests and remote branches come from the
625
+ `source` provider (`Source.listPullRequests`, `listPullRequestCommits`, `listBranches`, `deleteBranch`).
626
+
374
627
  ## Upgrading
375
628
 
376
- - **`holocron upgrade node <to>`** — patches every Node.js version pin
629
+ - **`holocron repo upgrade node <to>`** — patches every Node.js version pin
377
630
  (`engines.node`, `.nvmrc`, `.node-version`, `.github/workflows/*`,
378
631
  `Dockerfile`, `.tool-versions`) to a new major.
379
- - **`holocron upgrade deps`** — bumps every `@theholocron/*` pin in
632
+ - **`holocron repo upgrade deps`** — bumps every `@theholocron/*` pin in
380
633
  `pnpm-workspace.yaml` (`catalog:` and every named `catalogs.*`) to its latest
381
634
  published version, then migrates `holocron.config.ts` from the 7.x preset
382
635
  shape (`const { repo, workflows } = node()` + `repo.requiredChecks` +
383
636
  `workflows:`) to the current composed-preset API (`const preset = node()` +
384
637
  `...preset` + `tasks:` + `extraRequiredChecks:`). Mechanical transforms only —
385
- review the result, then `pnpm install && holocron ci`. `--pins-only` skips
638
+ review the result, then `pnpm install && holocron run ci`. `--pins-only` skips
386
639
  the config migration; `--dry-run` prints without writing.
387
640
 
388
641
  ## Auth — fine-grained tokens
@@ -397,37 +650,56 @@ holocron auth set github.issues ghp_xxx # issue management
397
650
  holocron auth set github.sync ghp_xxx # sync-github workflow templates
398
651
  holocron auth set github.release ghp_xxx # semantic-release
399
652
  holocron auth set github.admin ghp_xxx # setup, secrets, environments
653
+ holocron auth set github.user-sync ghp_xxx # the files that link GitHub accounts to other services' members
400
654
  ```
401
655
 
402
656
  The resolution chain per capability is:
403
657
 
404
- ```
658
+ ```text
405
659
  --token flag → HOLOCRON_<FEATURE>_TOKEN env var → keyring("github.<feature>")
406
660
  ```
407
661
 
408
662
  See [`docs/tokens.md`](../../docs/tokens.md) for required PAT scopes per feature.
409
663
 
664
+ A plugin lists the tokens it takes in a `tokens: PluginToken[]` export (each resolver exposes its own as `.token`), as
665
+ `{ envName, vendorEnvName?, keyringKey, verifiable?, optional? }`, so `holocron doctor tokens`, `doctor credentials` and
666
+ `auth export` can find them. Set `optional: true` on a token the plugin only falls back to, such as the Discord
667
+ webhook a post uses when it names no channel: the checks that expect every listed token do not expect it, and
668
+ `auth export` marks it `(optional)` when it has no value. `verifiable: false` marks a token `verifyToken` does not
669
+ apply to.
670
+
410
671
  Additional `auth` subcommands:
411
672
 
412
673
  ```sh
413
674
  holocron auth check github.read # re-verify a stored token
414
675
  holocron auth unset github.read # remove a stored token
415
676
  holocron auth list # show all stored providers
677
+ holocron auth export # tokens as NAME=value lines in a private .credentials, to import into a credentials environment
678
+ holocron auth export --only HOLOCRON_SENTRY_TOKEN # one token, to the clipboard
679
+ holocron auth export --blank --vendor-names --file --only VERCEL_TOKEN --only HOLOCRON_RELEASE_TOKEN # the stored ones filled, the rest empty
680
+ holocron github-app create --name "My App - dev" --webhook-url https://<tunnel>/api/webhook --manifest apps/sentinel/github-app.manifest.json # a GitHub App from a manifest; its id, key and webhook secret to a private .credentials
681
+ holocron tunnel up --name sentinel-dev --hostname sentinel-dev.example.dev --port 3000 --run # a named tunnel with a stable hostname to a local port
682
+ holocron dev # the app, its vault variables and the tunnel, in one command (settings: `dev` in holocron.config)
416
683
  ```
417
684
 
418
685
  ## Logging
419
686
 
420
687
  Operational output goes through `@theholocron/observability/logger` — separate
421
- from the user-facing `print` surface. Global flags:
688
+ from the user-facing `print` surface. Local/interactive runs are quiet by
689
+ default: no colorized or raw structured console output, regardless of the
690
+ resolved level (Axiom shipping, when configured, is unaffected). CI is
691
+ untouched — its existing stdout output still appears. Global flags:
422
692
 
423
693
  ```sh
424
- holocron doctor --verbose # log level → debug (full structured output)
425
- holocron doctor --quiet # log level → error (suppress info + warn)
694
+ holocron doctor --log debug # show console output at this level (opt back in)
695
+ holocron doctor --verbose # log level → debug, and shows console output
696
+ holocron doctor --quiet # log level → error, and shows console output
426
697
  holocron doctor --debug # print "Run ID: <uuid>" at command end for Axiom lookup
427
698
  ```
428
699
 
429
- Level resolution (highest priority first): `--verbose` / `--quiet` →
430
- `HOLOCRON_LOG_LEVEL` → `log.level` in `holocron.config` → `"info"`.
700
+ Level resolution (highest priority first): `--log <level>` → `--verbose` /
701
+ `--quiet` → `HOLOCRON_LOG_LEVEL` → `log.level` in `holocron.config` →
702
+ `"info"`.
431
703
 
432
704
  ```ts
433
705
  export default defineConfig({
@@ -439,7 +711,16 @@ Axiom shipping activates when a token (`HOLOCRON_AXIOM_TOKEN` / `AXIOM_TOKEN`
439
711
  → OS keyring `axiom.<org>` → `axiom`) **and** a dataset
440
712
  (`HOLOCRON_AXIOM_DATASET` / `AXIOM_DATASET` → `log.axiom.dataset` in
441
713
  `holocron.config`) both resolve; env vars win. The token is never read from a
442
- config file. See the [logging guide](https://docs.theholocron.dev/holocron/logging/).
714
+ config file.
715
+
716
+ The dataset side of that resolution is **execution-context-aware** (ADR-0012):
717
+ a `global`-context command (`clone`, `new`, `auth set`, `upgrade node`, `plugin
718
+ create`, …) always ships to holocron's own dataset regardless of `$PWD` — it
719
+ isn't "about" any repo, so routing it through whichever repo's `.envrc`
720
+ happens to be active would be wrong. `repo-aware` / `workspace` commands
721
+ (`doctor`, `deploy`, `sync`, …) keep the env-var/config chain above, so a
722
+ per-repo `HOLOCRON_AXIOM_DATASET` — e.g. via a `.envrc` + `direnv` — separates
723
+ each consuming repo's logs. See the [logging guide](https://docs.theholocron.dev/holocron/logging/).
443
724
 
444
725
  ### Telemetry
445
726
 
@@ -468,38 +749,72 @@ export default defineConfig({
468
749
 
469
750
  Each SDK sits behind an interface from `@theholocron/observability` —
470
751
  `ErrorSink` (Sentry) / `AnalyticsSink` (PostHog); the adapters, and the only
471
- `@sentry/node` / `posthog-node` imports, live in that package. `telemetry.ts`
752
+ `@sentry/node` / `posthog-node` imports, live in that package. `observability/telemetry.ts`
472
753
  holds the orchestration + the Holocron-specific credential resolution
473
- (`telemetry/resolve.ts`). See the
754
+ (`observability/resolve-telemetry.ts`). See the
474
755
  [telemetry guide](https://docs.theholocron.dev/holocron/telemetry/).
475
756
 
757
+ ### ESLint bundle options
758
+
759
+ Most repos need nothing here — `@theholocron/eslint-config`'s `library()`
760
+ bundle resolves with zero committed file (Bucket A: `eslint --config
761
+ <shared path>`, no per-repo `eslint.config.ts` needed). A package with a
762
+ genuine, deliberate exception — e.g. Web Crypto globals a Node-targeted
763
+ package still needs, exempted via `library()`'s own `browserPackages`
764
+ option in that package's own `eslint.config.ts` — should also declare the
765
+ same paths in `holocron.config`'s `eslint.browserPackages`:
766
+
767
+ ```ts
768
+ export default defineConfig({
769
+ eslint: {
770
+ browserPackages: ["clients/github-client/src/app-auth"],
771
+ },
772
+ });
773
+ ```
774
+
775
+ This doesn't replace the package's own `eslint.config.ts` (local/CI linting
776
+ still resolves that file directly) — it's the signal Sentinel's centralized
777
+ static-analysis check (holocron#849/#858) reads instead, since that check
778
+ never reads a PR's own committed config files. Without it, Sentinel flags a
779
+ false-positive `eslint-plugin-n` node-builtins finding on exactly the files
780
+ the local override exists to exempt.
781
+
476
782
  ## What's in here
477
783
 
478
- - `src/capabilities/` — the 14 capability interfaces that providers
479
- implement
784
+ - `src/plugin/capabilities.ts` — the 20 capability interfaces that
785
+ providers implement
480
786
  - `src/config.ts` — config schema, `defineConfig`, `resolveConfig`,
481
787
  `CapabilityConfigPackage`
482
788
  - `src/config/load-config.ts` — `loadConfig` — reads `holocron.config.*`
483
789
  (file discovery via [`@theholocron/datapad`](../datapad))
484
790
  - `src/define-config.ts` — `defineConfig` typed pass-through
485
- - `src/logger.ts` — CLI-side `@theholocron/observability/logger` wiring
791
+ - `src/observability/logger.ts` — CLI-side `@theholocron/observability/logger` wiring
486
792
  (`buildCliLogger`, `resolveLogLevel`)
487
793
  - `src/loader.ts` — `PluginLoader` — dynamic-imports plugins, resolves
488
794
  capability config packages, builds the capability registry
489
795
  - `src/cli.ts` — yargs entry, dispatches subcommands. `holocron run` / `ci` are
490
796
  delegated to [`@theholocron/astromech`](../astromech) (`createAstromech`).
491
- `holocron sync` / `holocron setup` write each repo's `.github/workflows/*.yml`
492
- thin callers from `astromech.thinCallers()`; `holocron sync-github` pushes the
797
+ `holocron repo sync` / `holocron repo setup` write each repo's `.github/workflows/*.yml`
798
+ thin callers from `astromech.thinCallers()`; `holocron sync github` pushes the
493
799
  reusable `workflow_call` implementations + composite actions from
494
- `astromech.reusableTemplates()` to `theholocron/.github` (a pure sync target —
800
+ `astromech.reusableTemplates()` (written in `ci/`) to `theholocron/.github` (a pure sync target —
495
801
  never hand-edit its `.github/workflows/*`).
496
- - `src/commands/` — `setup`, `sync`, `doctor`, `deploy`, `secret set`,
497
- `secrets sync`, `publish`, `bump-versions`, `sync-github`, `upgrade node`,
498
- `upgrade deps`, `plugin create`, `auth`
499
- - `src/interactive-menu.ts` — the interactive fallback: `COMMAND_REGISTRY`,
500
- `launchMenu` (Layers 1–2, picks + spawns a fresh `holocron <command>`),
501
- `promptForPositionals` (Layer 3, called inline from each leaf command's
502
- `cli.ts` handler)
802
+ - `src/commands/` — `repo setup`, `repo sync`, `doctor`, `deploy`,
803
+ `monitoring check`, `secrets list`, `secrets set`, `secrets sync`, `package publish`,
804
+ `package bump-versions`, `package move-tag`, `sync github`, `repo upgrade node`,
805
+ `repo upgrade deps`, `new plugin`, `auth`, `notifications setup`,
806
+ `notifications channel add`, `notifications link`,
807
+ `notifications sync-roles`, `doctor ci`, `doctor credentials`, `doctor dns`, `doctor environments`, `doctor monitoring`, `doctor notifications`, `doctor repo`, `doctor secrets`, `doctor tokens`, `doctor variables`
808
+ - `src/commands/doctor-checks/` and `src/commands/deep-checks/` — the shared row
809
+ renderer and `declaredVsActual` helper, and `DEEP_CHECKS`, the registry every
810
+ `doctor <capability>` is listed in
811
+ - `src/interactive-menu/` — the interactive fallback: `command-registry`
812
+ (`COMMAND_REGISTRY`, each entry's `positionals`/`options`), `launch-menu`
813
+ (Layers 1–2, picks + spawns a fresh `holocron <command>`), `child-argv`
814
+ (builds the spawned argv + secret env), `menu-items`, `run-menu-entries`.
815
+ The generic prompting pieces it calls — `promptForPositionals`,
816
+ `promptForOptions` (Layer 3) — live in `src/ui/`, which has no knowledge
817
+ of commands.
503
818
 
504
819
  ## Status
505
820