Updated documentation

docs/UPGRADING.md

@@ -57,7 +57,9 @@ The errors are automatically sent to output via `feedback` package, as for the o
 ### `board attach` CLI command changed behaviour
 
 The `board attach` CLI command has changed behaviour: now it just pick whatever port and FQBN is passed as parameter and
-saves it in the `sketch.json` file, without any validity check or board autodetection.
+saves it in the `sketch.yaml` file, without any validity check or board autodetection.
+
+The `sketch.json` file is now completely ignored.
 
 ### `cc.arduino.cli.commands.v1.BoardAttach` gRPC interface command removal
 

docs/sketch-project-file.md

@@ -115,3 +115,24 @@ When using the profile-based build, the globally installed platforms and librari
 not be used in any way. In other words, the build is isolated from the system and will rely only on the resources
 specified in the profile: this will ensure that the build is portable and reproducible independently from the platforms
 and libraries installed in the system.
+
+## Default flags for Arduino CLI usage
+
+The sketch project file may be used to set the default value for some command line flags of the Arduino CLI, in
+particular:
+
+- The `default_fqbn` directive sets the default value for the `--fqbn` flag
+- The `default_port` directive sets the default value for the `--port` flag
+- The `default_protocol` directive sets the default value for the `--protocol` flag
+
+For example:
+
+```
+default_fqbn: arduino:avr:uno
+default_port: /dev/ttyACM0
+default_protocol: serial
+```
+
+With this configuration set, it is not necessary to specify the `--fqbn`, `--port`, or `--protocol` flags to the
+[`arduino-cli compile`](commands/arduino-cli_compile.md) or [`arduino-cli upload`](commands/arduino-cli_upload.md)
+commands when compiling or uploading the sketch.

docs/sketch-specification.md

@@ -68,14 +68,12 @@ the `data` folder, so any non-code files outside the `data` folder are stripped.
 
 #### `sketch.json`
 
-Arduino CLI and Arduino Web Editor use a file named sketch.json, located in the sketch root folder, to store sketch
-metadata.
+Arduino Web Editor use a file named `sketch.json`, located in the sketch root folder, to store sketch metadata. This
+file is not used by the Arduino CLI or the Arduino IDE, if you're not an Arduino Web Editor user you can safely ignore
+it.
 
-The `cpu` key contains the board configuration information. This can be set via
-[`arduino-cli board attach`](commands/arduino-cli_board_attach.md) or by selecting a board in the Arduino Web Editor
-while the sketch is open. With this configuration set, it is not necessary to specify the `--fqbn` or `--port` flags to
-the [`arduino-cli compile`](commands/arduino-cli_compile.md) or [`arduino-cli upload`](commands/arduino-cli_upload.md)
-commands when compiling or uploading the sketch.
+The `cpu` key contains the board configuration information. This can be set by selecting a board in the Arduino Web
+Editor while the sketch is open.
 
 The `included_libs` key defines the library versions the Arduino Web Editor uses when the sketch is compiled. This is
 Arduino Web Editor specific because all versions of all the Library Manager libraries are pre-installed in Arduino Web
@@ -88,6 +86,9 @@ This is an optional file named `sketch.yaml`, located in the root folder of the
 Inside the sketch project file the user can define one or more "profiles": each profile is a description of all the
 resources needed to build the sketch (platform and libraries each pinned to a specific version).
 
+The sketch project file is also used in the [`arduino-cli board attach`](commands/arduino-cli_board_attach.md) command
+to store the currently selected board and port.
+
 For more information see the [sketch project file](sketch-project-file.md) documentation.
 
 ### Secrets