@theholocron/cli 5.0.0-alpha.8 → 5.0.0-alpha.81

package/README.md

@@ -112,6 +112,52 @@ Additional `repo` fields recognised by `holocron setup`:
 | `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.                           |
 | `repo.properties` | `RepoProperties`                        | Org-level custom property values synced to the GitHub dashboard.                                                                                                           |
 
+### Custom properties synced to GitHub
+
+`holocron setup` and `holocron sync` both call `syncProperties()` with two
+kinds of fields — always one-way (`holocron.config.ts` → resolved →
+properties; properties are never a second editable source of truth):
+
+**Manual** — `repo.properties` states these explicitly:
+
+| Property                 | Value                                          |
+| ------------------------ | ---------------------------------------------- |
+| `lifecycle`              | `"active" \| "experimental" \| "deprecated"`   |
+| `open_source`            | `boolean`                                      |
+| `runtime_environment`    | `"node" \| "browser" \| "universal" \| "none"` |
+| `uses_external_packages` | `boolean`                                      |
+
+**Derived** — computed from resolved config + `package.json`, not a config field:
+
+| Property                           | Value                                                                                    |
+| ---------------------------------- | ---------------------------------------------------------------------------------------- |
+| `monorepo`                         | `boolean` — whether `pnpm-workspace.yaml` exists                                         |
+| `holocron_branch_protection_level` | the active `repo.protection` preset                                                      |
+| `holocron_profile`                 | repo archetype: `library` / `cli` / `plugin` / `template` / `app` / `docs` / `platform`  |
+| `holocron_capabilities`            | provider capability keys actually wired in `providers: {}` (`multi_select`)              |
+| `holocron_stack`                   | detected build/framework tooling — `next`, `vite`, `astro`, `tsdown`, … (`multi_select`) |
+| `holocron_compliance`              | `"compliant" \| "non-compliant"` against a minimal `source` + `ci` baseline              |
+
+Field definitions and derivation heuristics:
+`.notes/tech-holocron-platform.spec.md` → "Custom-properties sync — field
+definitions (#677)".
+
+The four derived fields' pure computation —
+`deriveProfile()`/`deriveStack()`/`deriveCapabilities()`/`deriveCompliance()`
+(plus their `HolocronProfile`/`DeriveProfileInput`/`PackageJsonLike` types)
+— is exported from this package's public entry point, separate from the
+local-filesystem reads (`readWorkspacePackageJsons()`) that gather their
+inputs here. `@theholocron/sentinel`'s `syncPropertiesFromConfig()` reuses
+these functions unchanged, gathering the same inputs over the GitHub API
+instead (D8 — one derivation, two input sources, not two
+implementations).
+
+`missingCapabilities(capabilities)` is `deriveCompliance()`'s sibling —
+same `REQUIRED_BASELINE` table, but returns _which_ required capabilities
+are absent rather than whether any are. `@theholocron/sentinel`'s
+`postCheckRun()` uses it to name what's missing on the check run it
+posts, instead of reporting pass/fail.
+
 ### Required status checks (`protection: "strict"`)
 
 `holocron setup` builds the branch-protection required-check list from the
@@ -146,6 +192,26 @@ lockfile — no coverable change) passes instead of hanging on a `codecov/*`
 required check that never posts. A re-run of `holocron setup` backfills both into
 an existing repo.
 
+### Default branch (`repo.defaultBranch`)
+
+```ts
+export default defineConfig({
+  repo: { protection: "strict", defaultBranch: "alpha" },
+  providers: { source: "github" },
+});
+```
+
+`holocron setup` syncs GitHub's repo-level default branch (`HEAD`) — what a
+fresh clone checks out, what `gh pr create`/the compare UI target by default,
+and what Sentinel's `validateConfig()` reads (it only ever reads config from
+the repo's default branch, never a PR ref — a deliberate security boundary).
+Omit this field to leave GitHub's current setting untouched; most repos never
+need it. It exists for a repo using a `main`/`alpha` prerelease-channel split
+where active development happens on a non-`main` branch: set this to that
+branch so Sentinel validates against what's actually being developed, then
+change it back once that branch merges to `main` for a stable cut and stops
+being the active branch.
+
 ### Git hooks
 
 ```ts