Merge pull request #843 from canonical/docs/accuracy

Doc: Improve accuracy

Author: dmitry-lyfar

docs/explanation/workshops/projects.rst

@@ -26,7 +26,7 @@ and run :command:`workshop launch`.
 Launching a workshop from a project
 establishes the relationship between the two
 that's required to actually start a workshop.
-This is achieved with a hidden :file:`.lock` file,
+This is achieved with a hidden :file:`.workshop.lock` file,
 which must remain in the project directory
 and must not be copied or stored externally, e.g., in a repository.
 

docs/how-to/develop-with-workshops/use-git.rst

@@ -100,7 +100,7 @@ From here, you can do whatever you like with your repo,
 because |ws_markup| handles
 :ref:`moving projects around <how_move_projects>` quite well.
 
-Don't forget to add the :file:`.lock` file to your :file:`.gitignore` file:
+Don't forget to add the :file:`.workshop.lock` file to your :file:`.gitignore` file:
 
 .. code-block:: console
 

docs/how-to/develop-with-workshops/use-workshops-with-ai-agents.rst

@@ -189,12 +189,12 @@ Even with :samp:`--yolo` or :samp:`--dangerously-skip-permissions`,
 any changes done by an agent remain contained inside the workshop.
 
 Save the definition and add it to :file:`.gitignore`,
-along with the :samp:`.lock` pattern:
+along with the :file:`.workshop.lock` file:
 
 .. code-block:: console
 
    $ cat >> .gitignore << EOF
-   *.lock
+   .workshop.lock
    .workshop.yaml
    EOF
 

docs/lychee.toml

@@ -40,6 +40,12 @@ exclude = [
     # gnu.org blocks bot User-Agents with 403; valid references
     "^https://www\\.gnu\\.org/",
 
+    # Intermittent "Connection reset by peer" (os error 104) on these hosts —
+    # transient CI-side network failures, not broken links
+    "^https://documentation\\.ubuntu\\.com/",
+    "^https://snapcraft\\.io/",
+    "^https://canonical\\.com/",
+
     # Transient overrides before public release
     "^https://ubuntu\\.com/workshop/",
     "^https://github\\.com/canonical/sdkcraft",

docs/reference/cli/workshopctl.rst

@@ -49,8 +49,9 @@ The arguments are as follows:
      - Can be :samp:`okay`, :samp:`waiting` or :samp:`error`.
 
    * - :samp:`<MESSAGE>`
-     - Required with :option:`!--code`
-     - Arbitrary string explaining the context of the error code;
+     - Required when :samp:`<STATUS>` is :samp:`waiting` or :samp:`error`;
+       not allowed with :samp:`okay`.
+     - Arbitrary string explaining the status;
        7–70 characters.
 
 

docs/tutorial/part-1-get-started.rst

@@ -355,7 +355,7 @@ and the revision shown matches the one in :command:`workshop info`.
 .. @artefact workshop .lock
 
 After launch, |ws_markup| tracks the project directory
-using a hidden :file:`.lock` file
+using a hidden :file:`.workshop.lock` file
 that must remain in the project directory
 and **not be copied or stored externally**, e.g., in a repository.
 
@@ -407,7 +407,7 @@ In the next step, you'll refresh an existing workshop.
 
 .. note::
 
-   Consider adding the :file:`.lock` file
+   Consider adding the :file:`.workshop.lock` file
    to your :file:`.gitignore` or similar ignore files:
 
    .. code-block:: console

internal/overlord/hookstate/ctlcmd/health.go

@@ -30,19 +30,21 @@ import (
 var (
 	shortHealthHelp = "Report the health status of an SDK"
 	longHealthHelp  = `
- The set-health command is called from within a workshop to inform the system of the
- SDK's overall health.
- 
- It can be called from any hook. An SDK can
- optionally provide a 'check-health' hook to manage these calls, which is
- then called periodically and with increased frequency while the SDK is
- "waiting". Any health regression will issue a warning to the user.
- 
- - status: One of okay, waiting, error.
- 
- - error-code: An optional note matching regex '[a-z](?:-?[a-z0-9])+', e.g. missing-cuda; up to 20 symbols.
+ The set-health command is called from within a workshop
+ to inform the system of the SDK's overall health.
+
+ It can only be called from the optional 'check-health' hook,
+ which runs when SDK health is checked (e.g. during launch or refresh)
+ and retried while the SDK reports as 'waiting'.
+ If the SDK reports an 'error', the hook fails with the provided message.
+
+ - status: One of 'okay', 'waiting', 'error'.
+
+ - code: An optional note matching regex '[a-z](?:-?[a-z0-9])+', e.g. 'missing-cuda';
+   3-30 characters. Must be empty if the status is 'okay'.
  
- - message: A user-friendly message expanding the status, 7-70 lines long. Required if the status is 'waiting' or 'error'.
+ - message: A user-friendly message expanding the status, 7-70 characters long.
+   Must be empty if the status is 'okay'; required if the status is 'waiting' or 'error'.
  `
 )