DOC-5432: Add pre-1.0 upgrade instructions

modules/ROOT/nav.adoc

@@ -2,6 +2,7 @@
 * xref:install.adoc[]
 * xref:manage-cli.adoc[]
 * xref:upgrade.adoc[]
+* xref:upgrade-pre-1.0.adoc[]
 * xref:uninstall.adoc[]
 
 .Quickstarts

modules/ROOT/pages/manage-cli.adoc

@@ -544,29 +544,250 @@ The {product} stores installation and configuration files in the following locat
 
 [cols="1h,2"]
 |===
-|File / Directory |Description
+|File / Folder |Description
 
 |`.astra`
-a|The `ASTRA_HOME` directory.
+a|The {product} home folder (`ASTRA_HOME`).
 
-_Default location_: `~/.astra` (macOS and Linux), `%USERPROFILE%\.astra` (Windows)
+_Default location_:
 
-The {product} stores the following items in this directory:
+* macOS: `~/.astra`
+* Linux: `~/.astra`, or `$XDG_DATA_HOME/astra` (if the `XDG_DATA_HOME` environment variable is set)
+* Windows: `%USERPROFILE%\.astra`
 
-* The {product} executable (scripted installations only)
-* Accessory executables downloaded by certain commands, such as `xref:commands:astra-db-cqlsh.adoc[]` and `xref:commands:astra-db-dsbulk.adoc[]`
-* {scb-brief}s
+The {product} stores the following items in this folder:
+
+* The `astra` executable (scripted installations only)
+* Accessory executables that are downloaded by certain commands, such as `xref:commands:astra-db-cqlsh.adoc[]` and `xref:commands:astra-db-dsbulk.adoc[]`
+* xref:astra-db-serverless:databases:secure-connect-bundle.adoc[{scb-brief}s]
 * Cache files for <<command-auto-completion,command auto-completion>>
 * Logs
 
-For more information about the `ASTRA_HOME` directory, see the {product} https://github.com/datastax/astra-cli?tab=readme-ov-file#home-folder-location[README].
+For more information about `ASTRA_HOME`, see the https://github.com/datastax/astra-cli?tab=readme-ov-file#home-folder-location[{product} README].
 
 |`.astrarc`
-|The {product} configuration file.
+a|The {product} configuration file.
+
+_Default location_:
 
-_Default location_: `~/.astrarc` (macOS and Linux), `%USERPROFILE%\.astrarc` (Windows)
+* macOS: `~/.astrarc`
+* Linux: `~/.astrarc`, or `$XDG_CONFIG_HOME/.astrarc` (if the `XDG_CONFIG_HOME` environment variable is set)
+* Windows: `%USERPROFILE%\.astrarc`
 
-This file stores your <<manage-configuration-profiles,configuration profiles>> and their associated application tokens.
+The {product} uses this file to store your <<manage-configuration-profiles,configuration profiles>> and their associated application tokens.
 
-For more information about the {product} configuration file, see the {product} https://github.com/datastax/astra-cli?tab=readme-ov-file#astrarc-location[README].
+For more information about the {product} configuration file, see the https://github.com/datastax/astra-cli?tab=readme-ov-file#astrarc-location[{product} README].
 |===
+
+=== Override the default home folder location
+
+You can override the default location of the {product} home folder (`.astra`) by setting the `ASTRA_HOME` environment variable.
+
+[tabs]
+======
+Set the environment variable dynamically::
++
+--
+Add the following line to your shell profile:
+
+[source,bash,subs="+quotes"]
+----
+eval "$(astra shellenv --home "**HOME_FOLDER_PATH**")"
+----
+
+Replace `**HOME_FOLDER_PATH**` with the full path to your preferred {product} home folder.
+--
+
+Set the environment variable directly::
++
+--
+Add the following line to your shell profile:
+
+[source,bash,subs="+quotes"]
+----
+export ASTRA_HOME=**HOME_FOLDER_PATH**
+----
+
+Replace `**HOME_FOLDER_PATH**` with the full path to your preferred {product} home folder.
+--
+======
+
+=== Override the default configuration file location
+
+You can override the default location of the {product} configuration file (`.astrarc`) by setting the `ASTRA_CONFIG_FILE` environment variable.
+
+[tabs]
+======
+Set the environment variable dynamically::
++
+--
+Add the following line to your shell profile:
+
+[source,bash,subs="+quotes"]
+----
+eval "$(astra shellenv --rc "**CONFIG_FILE_PATH**/.astrarc")"
+----
+
+Replace `**CONFIG_FILE_PATH**` with the full path to your preferred`.astrarc` configuration file.
+--
+
+Set the environment variable directly::
++
+--
+Add the following line to your shell profile:
+
+[source,bash,subs="+quotes"]
+----
+export ASTRARC=**CONFIG_FILE_PATH**/.astrarc
+----
+
+Replace `**CONFIG_FILE_PATH**` with the full path to your preferred `.astrarc` configuration file.
+--
+======
+
+[#command-output]
+== Command output formats and exit codes
+
+Most commands support the `-o` / `--output` option to specify the format of the command output:
+
+[source,shell,subs="+quotes"]
+----
+astra COMMAND -o **FORMAT**
+----
+
+The following output formats are available:
+
+* `human` (default): Human-readable format, optimized for command-line readability.
+* `json`: Structured JSON format, suitable for programmatic parsing.
+* `csv`: Comma-separated output format, ideal for data export and analysis.
+
+[tabs]
+======
+Human-readable::
++
+--
+The human-readable format uses tables, lists, and other visual elements to present information on the command line.
+--
+
+JSON::
++
+--
+Every command supporting JSON output will always return a response of exactly this schema:
+
+.JSON output schema
+[source,json]
+----
+{
+  "code": "OK" | "UNCAUGHT" | "DATABASE_NOT_FOUND" | "...",
+  "message": "Optional human-readable description",
+  "data": {
+    // Command-specific payload, may be an object, array, or primitive
+  },
+  "nextSteps": [
+    {
+      "command": "astra ...",
+      "comment": "Explanation of why/when to run this next"
+    }
+  ]
+}
+----
+
+All field names in the JSON output are in `camelCase`.
+
+[cols="1,1,2"]
+|===
+|Name |Type |Summary
+
+|`code`
+|`string`
+a|A string enum representing the exit code of the command.
+
+Common values include:
+
+* `OK`: command succeeded
+* `UNCAUGHT`: unexpected failure
+* `DATABASE_NOT_FOUND`: referenced resource missing
+* Other command-specific codes
+
+|`message`
+|`string`
+|Optional.
+A human-friendly message describing the result or error of the command.
+
+Not all commands include a message.
+
+|`data`
+|Any (type varies by command)
+|Freeform data specific to the command.
+Typically an object or array, but may be a primitive value (string, number, boolean, etc.) depending on the command.
+
+|`nextSteps`
+|`array` or `null`
+a|Optional.
+Only present if there are actionable next steps that you can take (it will never be an empty list).
+
+If present, it is an array of recommended next-step objects containing the following fields:
+
+* `command`: The command to run.
+* `comment`: An explanation of why/when to run this next.
+|===
+--
+
+CSV::
++
+--
+Every command supporting CSV output will always return an RFC-4180-compliant response of exactly this schema:
+
+.CSV output schema
+[source,csv]
+----
+code,message,data_field_1,data_field_2,...
+----
+
+All field names in the CSV output are in `snake_case`.
+
+The first row is always the header, defining the column names.
+Each subsequent row represents one data record from the command.
+
+The `code` and `message` fields may repeat for each row of data to keep the CSV schema consistent.
+Values may contain commas or newlines and be wrapped in quotes to ensure RFC-4180-compliant CSV output.
+
+[cols="1,1,2"]
+|===
+|Name |Type |Summary
+
+|`code`
+|`string`
+a|A string enum representing the exit code of the command.
+
+Common values include:
+
+* `OK`: command succeeded
+* `UNCAUGHT`: unexpected failure
+* `DATABASE_NOT_FOUND`: referenced resource missing
+* Other command-specific codes
+
+If no rows are returned, you should assume an implicit `OK` code.
+
+|`message`
+|`string`
+|Optional.
+A human-friendly message describing the result or error of the command.
+
+Not all commands include a message, and this field will be empty if there is nothing to report.
+
+|Additional data fields
+|Any (type varies by command)
+a|Command-specific fields representing the actual data returned.
+
+Fields may be empty if there is nothing to report.
+
+Column order is consistent per command.
+|===
+--
+======
+
+[NOTE]
+====
+For commands that issue GET requests, the `json` response generally contains the raw response from the server, whereas the `human` and `csv` formats contain a simplified version of the data.
+====

modules/ROOT/pages/uninstall.adoc

@@ -99,7 +99,7 @@ Manual removal::
 rm $(astra config path -p)
 ----
 
-. Delete the xref:ROOT:manage-cli.adoc#file-locations[{product} home directory]:
+. Delete the xref:ROOT:manage-cli.adoc#file-locations[{product} home folder]:
 +
 [source,shell]
 ----
@@ -229,7 +229,7 @@ Manual removal::
 rm -f $(astra config path -p)
 ----
 
-. Delete the xref:ROOT:manage-cli.adoc#file-locations[{product} home directory]:
+. Delete the xref:ROOT:manage-cli.adoc#file-locations[{product} home folder]:
 +
 [source,powershell]
 ----
@@ -251,7 +251,7 @@ For more information, see the https://learn.microsoft.com/en-us/powershell/modul
 Homebrew::
 +
 --
-. Delete the {product} home directory (`xref:ROOT:manage-cli.adoc#file-locations[~/.astra]`) and optionally its configuration file (`xref:ROOT:manage-cli.adoc#file-locations[~/.astrarc]`):
+. Delete the {product} home folder (`xref:ROOT:manage-cli.adoc#file-locations[~/.astra]`) and optionally its configuration file (`xref:ROOT:manage-cli.adoc#file-locations[~/.astrarc]`):
 +
 .. Run the `xref:commands:astra-nuke.adoc[]` command:
 +

modules/ROOT/pages/upgrade-pre-1.0.adoc

@@ -0,0 +1,49 @@
+= Upgrade from pre-1.0 versions of the {product}
+:navtitle: Upgrade from pre-1.0 versions
+
+// Author's note: Once we get further away from the 1.0 release, we can probably move the content of this page into a section of on the main upgrade.adoc page.
+
+{product} 1.0 and later do not support xref:ROOT:upgrade.adoc[in-place upgrades] from versions earlier than 1.0.
+
+If you have an earlier version installed, you must delete the `astra` executable before you can install the latest version:
+
+[tabs,sync-group-id=platforms]
+======
+macOS and Linux::
++
+--
+[source,shell]
+----
+rm $(which astra)
+----
+
+This command does not delete your xref:ROOT:manage-cli.adoc#file-locations[{product} home folder and configuration file] (`.astra` and `.astrarc`).
+Leave these files in place so that the new version of the {product} can continue to connect using your existing configuration.
+--
+
+Homebrew::
++
+--
+[source,shell]
+----
+brew uninstall datastax/astra-cli/astra-cli
+----
+
+Uninstalling with Homebrew does not delete your xref:ROOT:manage-cli.adoc#file-locations[{product} home folder and configuration file] (`.astra` and `.astrarc`).
+Leave these files in place so that the new version of the {product} can continue to connect using your existing configuration.
+--
+======
+
+After you delete the old `astra` executable, follow the instructions in xref:ROOT:install.adoc[] to install the latest version.
+
+.Breaking changes in version 1.0
+[IMPORTANT]
+====
+{product} version 1.0 is largely backwards-compatible with pre-1.0 versions.
+However, there are some changes that might break certain scripted usage, such as:
+
+* New standardized xref:ROOT:manage-cli.adoc#output-formats[JSON and CSV output formats and exit codes].
+
+* Minor command and flag name changes.
+For a full list of name changes, see the https://github.com/datastax/astra-cli?tab=readme-ov-file#whats-changed[release notes].
+====