[BryanFRD]

Closes #1126

A file listed under include now has its own schema, so editors autocomplete and validate it:

{
  "$schema": "https://ferrflow.com/schema/ferrflow-package.json",
  "name": "api"
}

• schema/ferrflow-package.json: the package entry's properties and $defs from ferrflow.json, with name required, path optional and additionalProperties: false.
• ferrflow schema --package prints it, bundled in the binary like the root schema.
• Tests fail when it drifts from ferrflow.json: every property and $defs must match, and every $ref must resolve inside the file.
• Docs: README and the ferrflow schema section of the CLI reference, EN and FR.

This work was written on 2026-08-25 right after #932 but never opened. The first commit is that original work. The second resyncs the package schema with what ferrflow.json gained since (buildMetadata per package, calver-short-seq, the galaxyyml, cabal and cmake formats), which the drift tests caught.

Not in this PR: serving the file at ferrflow.com/schema/ferrflow-package.json needs a copy in FerrFlow-Cloud/site/public/schema/. Until then the $schema URL above 404s, and ferrflow schema --package --output is the working path.

Verified: cargo fmt --check, cargo clippy --all-targets -D warnings, cargo test (2445 passed), and ferrflow schema --package prints the package schema.

[ferrfleet]

Schema, CLI wiring and drift tests all check out: I verified locally that every property of the root schema's package item is present and identical in schema/ferrflow-package.json, that $schema is the only extra key, that $defs matches, and that $schema in an included file is filtered out of the unknown-key warning (src/config/unknown_keys.rs), so the README snippet parses cleanly. required: ["name"] matches the loader, which defaults path to the fragment's directory.

One blocking finding on the path description, one nit on the not-yet-served URL. No cargo in this environment, so I did not run the test suite.

[ferrfleet]

Blocking: this description is inherited from the root schema and is wrong for an included file. fragment_path in src/config/include.rs joins path onto the fragment's own directory, not the repo root (fragment_path_is_relative_to_the_fragment_not_the_root pins it), and this also contradicts the file's own top-level description five lines up. Someone reading the editor tooltip writes "path": "services/api" inside services/api/ferrflow.json and gets services/api/services/api.

No suggestion block, because the fix has to move in two places at once: package_schema_describes_the_same_package_as_the_root_schema asserts every inline property is identical, so any reword here fails it. I'd special-case path in that loop, comparing the two values with description stripped so type and the rest still have to match, and set the description here to something like Path to the package root, relative to this file's directory. Defaults to that directory when omitted. Dropping path from the drift check entirely is simpler but gives up the type check on the key that matters most.

[ferrfleet]

Nit: as your description says, this URL 404s until FerrFlow-Cloud/site/public/schema/ has the copy, so merged as-is the README hands people a snippet whose schema their editor cannot resolve. Landing the cloud copy first and merging this after costs nothing and avoids a window where the documented path is broken.

Related: the root schema is also mirrored in-repo at docs/site/data/schema.json (byte-identical to schema/ferrflow.json); the package schema has no counterpart there. Worth checking whether whatever consumes that copy needs one.