feat(forge_config): inject $schema key into generated config for editor validation

[tusharmath]

Summary

Automatically inject a $schema key into generated Forge config files, enabling real-time editor validation and IntelliSense auto-complete for all configuration fields.

Context

Forge generates a TOML config file (forge.yaml / forge.default.yaml) that users edit by hand, but editors had no way to validate its fields or offer completions. The project already ships a forge.schema.json, but nothing linked the generated config to that schema. This change wires the two together automatically so every generated config benefits from editor tooling without any manual setup.

As a secondary improvement, the doc comments on every ForgeConfig field and the corresponding description strings in forge.schema.json have been rewritten for accuracy, completeness, and consistent style.

Changes

• crates/forge_config/src/writer.rs: Prepends "$schema" = "https://forgecode.dev/schema.json" as the first key of every config file written by ConfigWriter::write. The rest of the serialized TOML follows unchanged.
• crates/forge_config/src/config.rs: Rewrote all Rust doc comments on ForgeConfig fields to be more precise and consistent (e.g. clarifying units, edge-case behaviour when None, and correct capitalisation of "Forge").
• forge.schema.json: Synced all description strings to match the updated Rust doc comments so the schema tooltips shown in editors are accurate.

Key Implementation Details

The schema injection is done at the string level after TOML serialisation, keeping the change minimal and independent of serde or toml_edit internals. The schema URL (https://forgecode.dev/schema.json) is the canonical public location for the schema, so editors that support JSON Schema for TOML (VS Code with Even Better TOML, JetBrains IDEs, Neovim with SchemaStore, etc.) will fetch and apply it automatically.

Use Cases

• Open forge.default.yaml (or any generated config) in VS Code and get instant field descriptions, type checking, and auto-complete.
• Misconfigured fields (wrong type, unknown key) are underlined in the editor before running Forge.
• New contributors can explore available config options directly in their editor without consulting external docs.

Testing

# Generate a fresh config and verify the $schema key is present as the first line
cargo test -p forge_config

# Manually inspect a generated config
cargo run -- init
head -1 forge.default.yaml
# Expected: "$schema" = "https://forgecode.dev/schema.json"

Links

• Schema file: forge.schema.json
• Config writer: crates/forge_config/src/writer.rs

[graphite-app]

The $schema key is a JSON Schema convention that is not recognized by TOML parsers or editors. While the code successfully writes "$schema" = "https://forgecode.dev/schema.json" as a valid TOML key-value pair, this will not enable IDE validation, auto-complete, or inline documentation as described in the PR. Modern editors only recognize $schema for JSON files, not TOML files. The schema file forge.schema.json is a JSON Schema designed for JSON, but the config file being written is TOML format (using toml_edit::ser::to_string_pretty).

To fix this, either:

1. Switch the config format from TOML to JSON, or
2. Use a TOML-specific schema mechanism if one exists (though TOML has no standard schema validation like JSON Schema)
3. Document that users need to manually configure their editor to associate the schema with TOML files (which most editors don't support)

Suggested change

	let config_toml = toml_edit::ser::to_string_pretty(&self.config)?;
	let contents =
	format!("\"$schema\" = \"https://forgecode.dev/schema.json\"\n\n{config_toml}");
	let config_json = serde_json::to_string_pretty(&self.config)?;
	let mut schema_obj: serde_json::Value = serde_json::from_str(&config_json)?;
	if let serde_json::Value::Object(ref mut map) = schema_obj {
	map.insert(
	"$schema".to_string(),
	serde_json::Value::String("https://forgecode.dev/schema.json".to_string()),
	);
	}
	let contents = serde_json::to_string_pretty(&schema_obj)?;

Spotted by Graphite



Is this helpful? React 👍 or 👎 to let us know.