docs: various improvements and standardizing terms (#689)

Signed-off-by: Grant Linville <[email protected]>

docs/docs/02-examples/02-api.md

@@ -105,4 +105,4 @@ For a more advanced DigitalOcean chatbot, see our [DigitalOcean Agent](https://g
 
 To read more about OpenAPI tools in GPTScript, see the [OpenAPI Tools](../03-tools/03-openapi.md) article.
 
-To read more about credential storage in GPTScript, see the [Credentials](../02-credentials.md) article.
+To read more about credential storage in GPTScript, see the [Credentials](../06-credentials.md) article.

docs/docs/03-tools/01-using.md

@@ -1,12 +1,17 @@
 # Using Tools
-In GPTScript, tools are used to extend the capabilities of a script. The idea behind them is that AI performs better when it has very specific instructions for a given task. Tools are a way to break-up the problem into smaller and more focused pieces where each tool is responsible for a specific task. A typical flow like this is to have a main script that imports a set of tools it can use to accomplish its goal.
+
+In GPTScript, tools are used to extend the capabilities of a script.
+The idea behind them is that AI performs better when it has very specific instructions for a given task.
+Tools are a way to break up the problem into smaller and more focused pieces where each tool is responsible for a specific task.
+A typical pattern is to have a main script that imports a set of tools it can use to accomplish its goal.
 
 GPTScripts can utilize tools in one of three ways:
 1. Built-in system tools
 2. In-script tools
 3. External tools
 
 ### System Tools
+
 All GPTScripts have access to system tools, like `sys.read` and `sys.write`, that can be used without any additional configuration.
 
 ```yaml
@@ -16,11 +21,14 @@ Read all of the files in my current directory, do not recurse over any subdirect
 ```
 
 System tools are a set of core tools that come packaged with GPTScript by default.
+To see a list of the system tools, run `gptscript --list-tools`.
 
 ### In-Script Tools
-Things get more interesting when you start to use custom tools.
 
-The most basic example of this is an in-script tool that is defined in the same file as the main script. This is useful for breaking up a large script into smaller, more manageable pieces.
+Things get more interesting when you start to write your own tools.
+
+The most basic example of this is an in-script tool that is defined in the same file as the main script.
+This is useful for breaking up a large script into smaller, more manageable pieces.
 
 ```yaml
 tools: random-number
@@ -35,7 +43,9 @@ Select a number at random between 1 and 100 and return only the number.
 ```
 
 ### External Tools
-You can refer to GPTScript tool files that are served on the web or stored locally. This is useful for sharing tools across multiple scripts or for using tools that are not part of the core GPTScript distribution.
+
+You can refer to GPTScript tool files that are served on the web or stored locally.
+This is useful for sharing tools across multiple scripts or for using tools that are not part of the core GPTScript distribution.
 
 ```yaml
 tools: https://get.gptscript.ai/echo.gpt
@@ -51,9 +61,11 @@ tools: echo.gpt
 Echo the phrase "Hello, World!".
 ```
 
-You can also refer to OpenAPI definition files as though they were GPTScript tool files. GPTScript will treat each operation in the file as a separate tool. For more details, see [OpenAPI Tools](03-openapi.md).
+You can also refer to OpenAPI definition files as though they were GPTScript tool files.
+GPTScript will treat each operation in the file as a separate tool. For more details, see [OpenAPI Tools](03-openapi.md).
 
 ### Packaged Tools on GitHub
+
 GPTScript tools can be packaged and shared on GitHub, and referred to by their GitHub URL. For example:
 
 ```yaml
@@ -64,5 +76,9 @@ Generate an image of a city skyline at night and write the resulting image to a
 Take this image and write a description of it in the style of pirate.
 ```
 
+:::important
+The GitHub URL must not be prefixed with `http://` or `https://`.
+:::
+
 When this script is run, GPTScript will locally clone the referenced GitHub repos and run the tools referenced inside them.
 For more info on how this works, see [Authoring Tools](02-authoring.md).

docs/docs/03-tools/02-authoring.md

@@ -2,11 +2,12 @@
 
 You can author your own tools for your use or to share with others.
 The process for authoring a tool is as simple as creating a `tool.gpt` file in the root directory of your project.
-This file is itself a GPTScript that defines the tool's name, description, and what it should do.
+This file is a GPTScript that defines the tool's name, description, and what it should do.
 
 ## Quickstart
 
-This is a guide for writing portable tools for GPTScript. The supported languages currently are Python, Node.js, and Go. This guide uses Python, but you can see documentation for the other language below.
+This is a guide for writing portable tools for GPTScript. The supported languages currently are Python, Node.js, and Go.
+This guide uses Python, but you can see documentation for the other languages below.
 
 ### 1. Write the code
 
@@ -65,17 +66,24 @@ gptscript github.com/<user>/<repo name> '{"url": "https://github.com"}'
 
 ## Sharing Tools
 
-GPTScript is designed to easily export and import tools. Doing this is currently based entirely around the use of GitHub repositories. You can export a tool by creating a GitHub repository and ensuring you have the `tool.gpt` file in the root of the repository. You can then import the tool into a GPTScript by specifying the URL of the repository in the `tools` section of the script. For example, we can leverage the `image-generation` tool by adding the following line to a GPTScript:
+GPTScript is designed to easily export and import tools.
+Doing this is currently based entirely around the use of GitHub repositories.
+You can export a tool by creating a GitHub repository and ensuring you have the `tool.gpt` file in the root of the repository.
+You can then import the tool into a GPTScript by specifying the URL of the repository in the `tools` section of the script.
+For example, we can leverage the `image-generation` tool by adding the following line to a GPTScript:
 
 ```yaml
 tools: github.com/gptscript-ai/dalle-image-generation
 
 Generate an image of a city skyline at night.
 ```
 
-### Supported Languages
+## Supported Languages
 
-GPTScript can execute any binary that you ask it to. However, it can also manage the installation of a language runtime and dependencies for you. Currently this is only supported for a few languages. Here are the supported languages and examples of tools written in those languages:
+GPTScript can execute any binary that you ask it to.
+However, it can also manage the installation of a language runtime and dependencies for you.
+Currently, this is only supported for a few languages.
+Here are the supported languages and examples of tools written in those languages:
 
 | Language  | Example                                                                                                        |
 |-----------|----------------------------------------------------------------------------------------------------------------|
@@ -84,10 +92,13 @@ GPTScript can execute any binary that you ask it to. However, it can also manage
 | `Golang`  | [Search](https://github.com/gptscript-ai/search) - Use various providers to search the internet                |
 
 
-### Automatic Documentation
+## Automatic Documentation
 
-Each GPTScript tool is self-documented using the `tool.gpt` file. You can automatically generate documentation for your tools by visiting `tools.gptscript.ai/<github repo url>`. This documentation site allows others to easily search and explore the tools that have been created. 
+Each GPTScript tool is self-documented using the `tool.gpt` file.
+You can automatically generate documentation for your tools by visiting `https://tools.gptscript.ai/<github repo url>`.
+This documentation site allows others to easily search and explore the tools that have been created. 
 
-You can add more information about how to use your tool by adding an `examples` directory to your repository and adding a collection of `.gpt` files that demonstrate how to use your tool. These examples will be automatically included in the documentation.
+You can add more information about how to use your tool by adding an `examples` directory to your repository and adding a collection of `.gpt` files that demonstrate how to use your tool.
+These examples will be automatically included in the documentation.
 
 For more information and to explore existing tools, visit [tools.gptscript.ai](https://tools.gptscript.ai).

docs/docs/03-tools/03-openapi.md

@@ -42,7 +42,7 @@ Will be resolved as `https://api.example.com/v1`.
 ## Authentication
 
 :::warning
-All authentication options will be completely ignored if the server uses HTTP and not HTTPS.
+All authentication options will be completely ignored if the server uses HTTP and not HTTPS, unless the request is for `localhost` or 127.0.0.1.
 This is to protect users from accidentally sending credentials in plain text.
 HTTP is only OK, if it's on localhost/127.0.0.1.
 :::

docs/docs/03-tools/04-credential-tools.md

@@ -13,7 +13,7 @@ Here is a simple example of a credential provider tool that uses the builtin `sy
 
 ```yaml
 # my-credential-tool.gpt
-name: my-credential-tool
+Name: my-credential-tool
 
 #!/usr/bin/env bash
 
@@ -27,25 +27,31 @@ echo "{\"env\":{\"MY_ENV_VAR\":\"$credential\"}}"
 Continuing with the above example, this is how you can use it in a script:
 
 ```yaml
-credentials: my-credential-tool.gpt
+Credentials: my-credential-tool.gpt as myCred
 
 #!/usr/bin/env bash
 
 echo "The value of MY_ENV_VAR is $MY_ENV_VAR"
 ```
 
+:::note
+GPTScript accepts `Cred:`, `Creds:`, `Credential:`, and `Credentials:` as valid directives.
+:::
+
 When you run the script, GPTScript will call the credential provider tool first, set the environment variables from its
 output, and then run the script body. The credential provider tool is called by GPTScript itself. GPTScript does not ask the
 LLM about it or even tell the LLM about the tool.
 
 If GPTScript has called the credential provider tool in the same context (more on that later), then it will use the stored
 credential instead of fetching it again.
 
+To delete the credential that just got stored, run `gptscript credential delete myCred`.
+
 You can also specify multiple credential tools for the same script, but they must be on separate lines:
 
 ```yaml
-credentials: credential-tool-1.gpt
-credentials: credential-tool-2.gpt
+Credentials: credential-tool-1.gpt
+Credentials: credential-tool-2.gpt
 
 (tool stuff here)
 ```
@@ -56,7 +62,7 @@ GPTScript also provides a generic credential tool (`github.com/gptscript-ai/cred
 where you only need to set one environment variable. Here is an example of how to use it:
 
 ```yaml
-credentials: github.com/gptscript-ai/credential as myCredentialName with MY_ENV_VAR as env and "this message will be displayed to the user" as message and key as field
+Credentials: github.com/gptscript-ai/credential as myCredentialName with MY_ENV_VAR as env and "this message will be displayed to the user" as message and key as field
 
 (tool stuff here)
 ```
@@ -66,24 +72,24 @@ the environment variable `MY_ENV_VAR` and stored in a credential called `myCrede
 
 See [the repo](https://github.com/gptscript-ai/credential) for more information.
 
-## Credential Tool Arguments
+## Credential Tool Parameters
 
-A credential tool may define arguments. Here is an example:
+A credential tool may define parameters. Here is an example:
 
 ```yaml
-name: my-credential-tool
-args: env: the environment variable to set
-args: val: the value to set it to
+Name: my-credential-tool
+Parameter: env: the environment variable to set
+Parameter: val: the value to set it to
 
 #!/usr/bin/env bash
 
 echo "{\"env\":{\"$ENV\":\"$VAL\"}}"
 ```
 
-When you reference this credential tool in another file, you can use syntax like this to set both arguments:
+When you reference this credential tool in another file, you can use syntax like this to set both parameters:
 
 ```yaml
-credential: my-credential-tool.gpt with MY_ENV_VAR as env and "my value" as val
+Credential: my-credential-tool.gpt with MY_ENV_VAR as env and "my value" as val
 
 (tool stuff here)
 ```
@@ -92,7 +98,7 @@ In this example, the tool's output would be `{"env":{"MY_ENV_VAR":"my value"}}`
 
 ## Storing Credentials
 
-By default, credentials are automatically stored in the credential store. Read the [main credentials page](../02-credentials.md)
+By default, credentials are automatically stored in the credential store. Read the [main credentials page](../06-credentials.md)
 for more information about the credential store.
 
 :::note
@@ -105,7 +111,7 @@ will not be stored in the credentials store.
 When you reference a credential tool in your script, you can give it an alias using the `as` keyword like this:
 
 ```yaml
-credentials: my-credential-tool.gpt as myAlias
+Credentials: my-credential-tool.gpt as myAlias
 
 (tool stuff here)
 ```
@@ -121,8 +127,7 @@ A credential context is basically a namespace for credentials. If you have multi
 you can switch between them by defining them in different credential contexts. The default context is called `default`,
 and this is used if none is specified.
 
-You can set the credential context to use with the `--credential-context` flag when running GPTScript. For
-example:
+You can set the credential context to use with the `--credential-context` flag when running GPTScript. For example:
 
 ```bash
 gptscript --credential-context my-azure-workspace my-azure-script.gpt
@@ -181,3 +186,21 @@ In this example, `toolA` provides the variables `ENV_VAR_1` and `ENV_VAR_2`,
 This will read the values of `ENV_VAR_1` through `ENV_VAR_4` from the current environment and set them for the credential.
 This is a direct mapping of environment variable names. **This is not recommended when overriding credentials for
 multiple tools that use the same environment variable names.**
+
+## Credential Refresh (Advanced)
+
+Some use cases (such as OAuth) may involve the need to refresh expired credentials.
+To support this, your credential tool can return other fields besides `env` in its JSON output.
+This is the full list of supported fields in the credential tool output:
+
+- `env` (type: object) - The environment variables to set.
+- `expiresAt` (type: string, timestamp in RFC3339 format) - The time when the credential expires.
+- `refreshToken` (type: string) - The refresh token to use to refresh the credential.
+
+When GPTScript tries to use a credential that has a defined `expiresAt` time, it will check if the credential has expired.
+If the credential has expired, it will run the credential tool again, and the current value of the credential will be
+set to the environment variable `GPTSCRIPT_EXISTING_CREDENTIAL` as a JSON string. This way, the credential tool can check for
+that environment variable, and if it is set, get the refresh token from the existing credential and use it to refresh and return a new credential,
+typically without user interaction.
+
+For an example of a tool that uses the refresh feature, see the [Gateway OAuth2 tool](https://github.com/gptscript-ai/gateway-oauth2).