foldrun 1.2.0 → 1.3.0

package/docs/checks.md

@@ -238,11 +238,48 @@ today.
 
 ### config/unknown-field
 
-*warn.* A frontmatter key in an agent, flow or tool that is one or two
-letters away from a field foldrun reads: `tolls:`, `triger:`,
-`disallowed_tools:`. YAML accepts it, so it is silently ignored, and `tolls:
-[web]` leaves the agent with no tools. A key that looks like no known field
-is left alone, since another tool may own it.
+*warn or info.* A frontmatter key that this kind of file does not read. There
+are three cases, each with its own message:
+- **A near-miss** of a real field (`tolls:`, `triger:`, `disallowed_tools:`) is
+  a warning that names the field it meant. YAML accepts a typo, so it is
+  silently ignored, and `tolls: [web]` leaves the agent with no tools.
+- **A field read somewhere else** is a warning that says where it goes.
+  `timeout: 3600` on an agent is a step option, so it belongs under the step
+  in the flow. `language:` on a flow is read from the agent or `AGENTS.md`.
+- **A field like nothing foldrun reads** (`favourite_colour:`) is a note,
+  since another tool may own it.
+
+### config/wrong-type
+
+*warn.* The right field holding the wrong kind of value: a map where a list
+of names goes (`tools: {web: true}`), a list where one word goes. The runtime
+does not read it. The message says what the field takes.
+
+### config/invalid-value
+
+*warn.* A value that does nothing, or quietly does something else:
+- `effort: extreme` runs at the model's default;
+- `size: giant` becomes `large`;
+- `permissionMode:` other than `plan` is ignored;
+- `trigger: sometimes` never fires;
+- a `schedule:` the scheduler cannot read (`every day`) never fires. This is
+  checked with the scheduler's own cron parser;
+- an unknown HTTP method in `methods:` is dropped;
+- a duration that is not one (`debounce: soon`).
+
+Aliases count as valid: `effort: quick` is `low`. Fields another rule already
+checks in depth (`network:`, `limits:`, `timezone:`, `web:`) are left to it,
+so nothing is reported twice.
+
+### config/missing-field
+
+*warn.* A required field is absent: a skill with no `description:` is never
+loaded, because the model chooses skills by their descriptions.
+
+Every field these four rules know is listed, with its type and values, in one
+place in `@foldrun/core` (`frontmatter-fields.ts`). The editor's completions
+come from the same list, so what the editor suggests and what `check`
+accepts cannot drift apart.
 
 ### check/ignore-needs-reason
 

package/docs/tools.md

@@ -1787,6 +1787,13 @@ Run `scripts/pace.py --spent <amount> --budget <amount>` from this skill's
 folder, then report the verdict in one sentence.
 ```
 
+| field | |
+|---|---|
+| `name` | defaults to the folder's name |
+| `description` | **required**: what it does and when to use it. A skill without one is never loaded, because the model chooses skills by their descriptions |
+| `when` | run tags: the skill is loaded only on runs carrying one of them |
+| `license`, `compatibility`, `metadata`, `allowed-tools` | the Agent Skills format's optional fields. Accepted and carried, not read by foldrun |
+
 Only names and descriptions sit in context; the agent reads the full file when
 a task matches. So an agent can carry many skills for a few tokens each — which
 is the reason to move a procedure out of `agent.md` in the first place.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "foldrun",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Agents are just folders. Write them, check them, run them — on your machine.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
@@ -11,7 +11,7 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@foldrun/core": "^1.3.0"
+    "@foldrun/core": "^1.4.0"
   },
   "files": [
     "bin",

package/src/commands.mjs

@@ -999,6 +999,10 @@ function narrowCheck(findings, root, opts, label, accountRoot = root) {
     out = out.filter((f) => want.has(f.rule) || want.has(f.rule.split("/")[0]) || want.has(categoryOf(f.rule)));
   }
   if (opts.security) out = out.filter((f) => SECURITY_CATEGORIES.has(categoryOf(f.rule)));
+  // check's own skill rule already says a skill has no description, as an
+  // error; the schema's note would say it twice. Only when that error is
+  // still in the report — `--rule config/missing-field` keeps the note.
+  out = out.filter((f) => !(f.rule === "config/missing-field" && out.some((g) => g.file === f.file && g.rule === "skill/config" && /no description|needs name and description/.test(g.message))));
   const file = path.join(root, ".foldrun", "check-baseline.json");
   if (opts.writeBaseline) {
     const created = new Date().toISOString();