docs: sync the avocado.yaml schema from avocado-cli

[lee-reinhardt]

Problem

The avocado.yaml schema served at /schemas/avocado-config.json and rendered on the Config schema page was maintained by hand here and had drifted from the CLI. It was missing rootfs, initramfs, permissions, repos, connect and most extension keys, its top level accepted any key, and its $id returned 404.

avocado-cli now owns the schema (avocado-linux/avocado-cli#286). It is rebuilt from what the CLI actually reads, and the CLI warns about any key the schema doesn't describe. New projects from avocado init point editors at this site's copy, so the site has to serve the CLI's.

Change

• scripts/sync-schema.js fetches schemas/avocado-config.json from the latest avocado-cli release at build time. It uses the release, not main, so the site never documents keys a released CLI doesn't read yet. AVOCADO_CLI_SCHEMA_REF overrides the ref for previews. It follows sync-targets: a failed fetch, or a release that predates the schema (1.0.0-rc.5 today), keeps the committed snapshot.
• The build and npm start run it next to sync-references and sync-targets.
• src/schemas/avocado-config.json is replaced with the current avocado-cli schema, as the snapshot.
• The schema is prettier-ignored, like generated-targets.json: it is jq-formatted upstream and rewritten at build time. The copy under static/ is ignored too, so a local check run after a build still passes.

Testing

• bash scripts/checks.sh steps: lint, prettier --check ., the build and check-mermaid all pass. The sync logged avocado-linux/avocado-cli@1.0.0-rc.5 has no schemas/avocado-config.json; keeping the committed snapshot., and the built /schemas/avocado-config.json is byte-identical to the snapshot.
• The Config schema page, loaded in headless Chrome from the built site, renders every top-level property with its type and description, including the new sections.

Merging before the next CLI release is fine: every avocado.yaml in avocado-linux/references and avocado-os validates against this schema. After that release, builds pick up the released copy on their own.

[Copilot]

Copilot review overview

🔵 Needs a closer look

Unresolved moderate issues affect startup serving, schema rendering and validation, target overrides, and prerelease synchronization.

Review effort: Lite
Findings: None

What changed in this PR

Synchronizes the Avocado configuration schema from avocado-cli releases and integrates schema updates into builds and development startup.

Changes:

• Adds release-based schema syncing with fallback and ref overrides.
• Updates the committed CLI-owned schema snapshot.
• Integrates syncing into build/start workflows and ignores generated copies.

File	Summary	Findings
src/​scripts/​sync-schema.js	Fetches and validates the upstream schema.	Moderate: latest-release lookup may miss prereleases.
src/​scripts/​build.sh	Runs schema synchronization during builds.	No findings.
src/​schemas/​avocado-config.json	Replaces the hand-maintained schema snapshot.	Moderate: renderer incompatibility and missing constraints for feeds and SDK target overrides.
src/​package.json	Adds schema synchronization commands.	Moderate: startup does not copy the refreshed schema into static/.
src/​.prettierignore	Excludes generated schema files from formatting checks.	No findings.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[jetm]

Nothing blocking. sync-schema.js is resilient the way a build-time fetch needs to be: a 404 (a release predating the schema's move into avocado-cli) keeps the committed snapshot with a warning, and any other failure (network, rate limit, malformed JSON) is caught and falls back the same way rather than failing the build. JSON.parse validates before writing, and I confirmed the committed avocado-config.json itself parses cleanly. build.sh's ordering is correct - sync runs before the static/schemas copy, so the copy always picks up whatever the sync just wrote. The bulk of this diff is the vendored schema content itself, which the script's own comment says is owned by avocado-cli and taken from there rather than edited here, so I didn't audit it key by key.

One thing worth knowing, not blocking: sync-schema is now also in prestart, so every local npm start makes an unauthenticated call to api.github.com/repos/avocado-linux/avocado-cli/releases/latest. That endpoint's 60/hour anonymous rate limit is shared across everything else on a developer's IP, so someone restarting the dev server often could start seeing the fallback-to-snapshot warning during a busy session. Harmless since it degrades to the committed copy either way, but worth knowing if that warning shows up and looks alarming.