@@ -0,0 +1,99 @@
+# 2026.242.0504 — fix: add a root charly.yml so the candy CI gate is real
+
+## Summary
+
+Makes this repo's candy CI gate actually gate something.
+
+Without a root `charly.yml` a plugin repo is **project-less**: charly scans **no candies at
+all**, so the stock `charly box validate` step in `deploy.yml` exits 0 on any manifest —
+including one with a malformed `plugin.providers` entry. The step has been asserting
+nothing.
+
+A four-line `discover:` block is the whole fix. The candy becomes scannable, the CUE schema
+gate applies, and the **stock** step starts working — no workflow change needed. The file
+declares no entities of its own; it only tells charly where to look.
+
+Refs opencharly/charly#459.
+
+## How tested
+
+The mechanism and the fix were established on `opencharly/plugin-punktfunk`
+(opencharly/plugin-punktfunk#4), with a plain layer candy to isolate it — `box list candies`
+filters plugin candies out of its own output, so a plugin candy alone cannot show this:
+
+```
+# candy/plainlayer/charly.yml exists, no root charly.yml
+$ charly box list candies         # (nothing — not scanned at all)
+$ charly box validate             # exit 0 even with a bogus field in the candy
+
+# with the 4-line root charly.yml
+$ charly box list candies
+plainlayer [testing]
+$ charly box validate
+... notafield: field not allowed
+```
+
+And on a real plugin candy, before/after, same repo and command:
+
+```
+# `- verb:punktfunk` changed to `- notaclass:punktfunk`
+# BEFORE: exit 0
+# AFTER:
+charly: error: command "validate": 2 validation errors:
+  plugin.providers.0: invalid value "notaclass:punktfunk"
+    (out of bound =~"^(kind|deploy|verb|step|build|builder|command|loader|refs|agent-runtime|terminal):...")
+```
+
+**Consumers are unaffected**, which is the real risk of adding a root manifest — a consuming
+project might resolve the candy twice (once via its pinned subpath ref, once via the new
+`discover:`). Tested by injecting the manifest into the *fetched* checkout that
+`opencharly/distro-cachyos` resolves for a pinned plugin candy, then validating that project
+both ways: identical result, exit 0 either way.
+
+**This repo's own gate is the acceptance:** the `build` check on this PR runs
+`charly box validate` at this repo root against the pinned charly. It now scans this repo's
+candy, so a green check here is the first time that step has meant anything for this repo.
+
+## Rulebook compliance
+
+- **R0 (skills)** — `/charly-internals:plugin` (plugin repo layout, the candy-ref contract)
+  and `/charly-internals:git-workflow` loaded before the change.
+- **R1 (RCA)** — root-caused, and an earlier wrong hypothesis (that the legacy `candy/` walk
+  skipped the CUE gate) was disproved by the plain-layer probe above before this fix was
+  written.
+- **R2 (no split)** — this repo is fixed here, not deferred; the org-wide gap is being closed
+  across every affected plugin repo in the same sweep, tracked by opencharly/charly#459.
+- **R3 (no duplication)** — one gate per repo; the stock `charly box validate` step is made
+  to work rather than a second, parallel validation being bolted on.
+- **R4 (no workarounds)** — the supported mechanism (`discover:`) is used; no CI staging
+  hack, no suppression.
+- **R4a (fix the product first)** — the product-side option (make `validate` treat a
+  `candy/`-bearing dir as a project) was investigated and rejected: "returns nil for a
+  project-less directory" is a documented contract other resolve paths rely on, so the fix
+  belongs in the repo.
+- **R5 (hard cutover)** — additive; no deprecated path is left behind.
+- **R6 (git safety)** — feature branch, no force-push, no hook bypass.
+- **R7 (prove the gate)** — the before/after validate outputs are above, and this PR's own
+  `build` check is the gate running for real.
+- **R9 (deployed binary)** — N/A — no binary, no runtime path; the provider is untouched.
+- **R10 (fresh disposable proof)** — N/A — this change cannot reach a running deployment; it
+  changes what `charly` scans in the repo, which the validate A/B fully observes.
+- **RDD** — the high-risk assumption (that a root manifest might break remote consumption)
+  was proved before landing, with the cached-checkout A/B above.
+- **ADE** — N/A — no install content authored; the candy's `plan:` is unchanged.
+- **SDD** — N/A — no schema or generated code touched.
+- **Concurrency mandate** — N/A — a single four-line file.
+- **Architecture gate / placement** — correct: the repo declares its own shape; core keeps
+  its project-less contract unchanged.
+
+## Change classification
+
+- **Change class:** repo configuration — adds a root manifest so the existing CI gate has
+  input. No source, no workflow, no schema change.
+- **Verification gate:** `charly box validate` before/after with a deliberately malformed
+  manifest, a consumer-side resolution A/B, and this PR's own `build` check.
+- **Attribution tier:** `fully tested and validated` — the gate this change exists to repair
+  was exercised in both directions, and the consumer risk was tested, with output retained
+  above.
+
+*Assisted-by: Claude Code claude-opus-5[1m] (fully tested and validated)*