Merge pull request #323 from stateful/T-iteration-v2

docs: adding disclaimers

Author: edeediong

docs/configuration/reference.md docs/Reference/configuration.mddocs/configuration/reference.md renamed to docs/Reference/configuration.md

@@ -2,27 +2,25 @@
 runme:
   id: 01HG11HG1XY3V7DCQVQ32Q71ZZ
   version: v2.0
-sidebar_position: 4
-title: Reference
+sidebar_position: 1
+title: Options for Document and Cell
 ---
 
-# Reference
-
-Everything in one place.
+Executing code and commands in Runme can be done either at the [Document level](../configuration/document-level) or the [Cell level](../configuration/cell-level). This page is a reference for both features.
 
 ### **Document Options**
 
-Frontmatter in yaml, json, or toml on top of markdown document.
+Frontmatter in yaml, json, or toml on top of Markdown document.
 
 | Configuration  | Description                              | Default value             |
 | ------------- | ----------------------------------------- | ------------------------- |
-| cwd           | Overwrites the default working directory  | [markdown file's basedir] |
+| cwd           | Overwrites the default working directory  | [Markdown file's basedir] |
 | shell         | Overwrites shell with custom preference   | [system/user default]     |
 | skipPrompts   | Bypasses interactive prompts              | [system/user default]     |
 
 ### **Cell Options**
 
-Metadata inside markdown's fenced code blocks.
+Metadata inside Markdown's fenced code blocks.
 
 | Configuration          | Description                                                     | Default value            |
 | ---------------------- | --------------------------------------------------------------- | ------------------------ |
@@ -45,24 +43,4 @@ This feature can be used to prevent [prompting](../configuration/document-level)
 
 </Infobox>
 
-### **Supported MIME types**
-
-Runme supports the standard VS Code MIME types alongside custom Runme MIME types.
-
-**Standard VS Code MIME types**
-
-- text/plain
-- application/javascript
-- text/html
-- image/svg+xml
-- text/markdown
-- image/png
-- image/jpeg
-
-**MIME types for rendering code**
 
-- text/x-json
-- text/x-javascript
-- text/x-html
-- text/x-rust
-- text/x-LANGUAGE_ID for any other built-in or installed languages.

docs/Reference/flag.md

@@ -0,0 +1,61 @@
+---
+sidebar_position: 2
+title: Commands and Flags
+---
+
+
+
+Runme executes commands inside your runbooks, documentation, and READMEs. It parses commands directly from Markdown files to make them executable.
+
+### **NAME**
+
+Runme [command]: Specific commands or actions in Runme to perform different tasks.
+
+Runme [flags]:  Optional configurations to modify the behavior of our Runme runbook.
+
+### **Runme Commands**:
+
+Below are some available commands within Runme
+
+| Commands         | Description                                                     |
+| ---------------------- | --------------------------------------------------------------- |
+| branch            | Suggest a branch name (aka branchGPT)  |
+| completion | Generate the autocompletion script for the specified shell                  |
+| extension              | Check your Stateful VS Code extension status                        |
+| fmt                    | Format a Markdown file into canonical format            |
+| help     | Help about any command    |
+| list            |  List available commands          |
+| login            | Log in to Runme (optional) |
+| logout              |    Log out from Runme                             |
+| open                 | Launch Runme in a headless web client  |
+| print          | Print a selected snippet              |
+| run             | Run a selected command          |
+| suggest           | Use our suggestion engine to give contextual advice |
+| tui | Run the interactive TUI                   |
+
+### **Runme Flags**
+
+Runme supported configuration flags.
+
+
+| Flags         | Description                                                     |
+| ---------------------- | --------------------------------------------------------------- |
+| --allow-unknown           | Display snippets without known executor (default true)  |
+| --allow-unnamed | Allow scripts without explicit names        |
+| --background            | Enable running background blocks as background processes                      |
+| --chdir string                   | Switch to a different working directory before executing the command (default "~/oss/docs.runme.dev")             |
+| --entries int    | Number of entries to show in TUI (default 5)   |
+| --env-order stringArray           |  List of environment files to load in order. (default [.env.local,.env])          |
+| --exit           | Exit TUI after running a command |
+| --filename string             |    Name of the README file (default "[README.md](http://readme.md/)")                        |
+| --filter string                | Regular expression to filter results, by filename and task name  |
+| --git-ignore         | Whether to respect .gitignore file(s) in project (default true)             |
+| -h, --help           | Help for Runme         |
+| --ignore-pattern stringArray          | Patterns to ignore in project mode (default [node_modules]) |
+| --insecure | Run command in insecure-mode                  |
+| --load-env          | Load env files from a local project. Control which files to load with --env-order (default true) |
+| --project string | Root project to find runnable tasks                 |
+| -s, --server string          | Server address to connect runner to |
+| --tls string | Directory for TLS authentication (default "~/Library/Application Support/runme/tls")                  |
+| -v, --version          |  -v, --version |
+

docs/Reference/index.md

@@ -0,0 +1,9 @@
+---
+sidebar_position: 7
+title: Reference
+---
+
+
+In this reference section, we will cover a range of terms, commands, and flags used on Runme and a brief description of these terminologies to enable you to understand each term and how they are used.
+
+In addition to common terms and commands in Runme, we have added configuration shortcuts designed to help you customize your runbook to suit your desired output.

docs/Reference/mime.md

@@ -0,0 +1,25 @@
+---
+sidebar_position: 4
+title: Supported MIME types
+---
+
+
+Runme supports the standard VS Code MIME types alongside custom Runme MIME types.
+
+**Standard VS Code MIME types**
+
+- text/plain
+- application/javascript
+- text/html
+- image/svg+xml
+- text/markdown
+- image/png
+- image/jpeg
+
+**MIME types for rendering code**
+
+- text/x-json
+- text/x-javascript
+- text/x-html
+- text/x-rust
+- text/x-LANGUAGE_ID for any other built-in or installed languages.

docs/architecture.md

@@ -5,13 +5,13 @@ title: Kernel Architecture
 
 Under the hood, much like other Notebook technologies such as Jupyter, Runme breaks down into the following parts:
 
-- A serializer that transforms markdown into executable cells with input and output
+- A serializer that transforms Markdown into executable cells with input and output
 - A portable runner interface that supports multimodal clients
 - A kernel that retains state across execution in sessions akin to a terminal
-- A raw-markdown editor (inside VS Code) client for the runner
+- A raw-Markdown editor (inside VS Code) client for the runner
 - A CLI client for the runner
 - A notebook client (inside VS Code) for the runner
-- A visual markdown viewer and editor (inside VS Code)
+- A visual Markdown viewer and editor (inside VS Code)
 
 The kernel architecture allows Runme to be seamlessly embedded into various User Interface technologies (notebook, editor, webapp, CLI) as well as headless excution as part of CI/CD pipelines.
 

docs/configuration/archiving.md

@@ -6,7 +6,7 @@ sidebar_position: 3
 title: Archiving Feature
 ---
 
-The Runme archiving feature is a tidy-up tool for users. It allows you to hide outputs generated from markdown cells to reduce clutter and preserve output for future reference. The archived files are securely stored in [Runme cloud](https://app.runme.dev/welcome) which can be accessible at any time.
+The Runme archiving feature is a tidy-up tool for users. It allows you to hide outputs generated from Markdown cells to reduce clutter and preserve output for future reference. The archived files are securely stored in [Runme cloud](https://app.runme.dev/welcome) which can be accessible at any time.
 
 On the Runme cloud, your data is encrypted both at rest and in transit, ensuring end-to-end security
 

docs/configuration/auto-save.md

@@ -6,22 +6,23 @@ sidebar_position: 3
 title: Auto-Save Feature
 ---
 
-Runme provides an easy and effective way to manage your records and outputs throughout your deployment. With the frequent changes, that occur in a cloud infrastructure deployment process, it is easy to lose track over time and we understand this.
-The Runme autosave feature automatically records and tracks every change and activity in your deployment process without any manual intervention to keep you updated and enhance team collaboration.
+Runme auto-save feature makes saving your outputs and progress easier. It is an effective way to manage your records and outputs throughout your deployment.
 
-## **Getting Started with Autosave**
+The Runme autosave feature automatically records and tracks every change and activity in your deployment process without manual intervention, so you can focus on your task and team collaboration without worrying about losing your outputs.
 
-Runme autosave feature goes beyond saving commands and running shell scripts. It is super helpful when automating tasks with changing or inconsistent instructions. Think of handling tasks that change each time or require information gathering at each step. Runme notebooks step in to manage these tasks, providing a consistent and standard way to run automated processes, and keeping you informed at every step.
+## **How Runme Auto-Save Feature Works**
+
+Runme auto-save feature goes beyond saving commands and running shell scripts. It uses the'session output’ feature to provide advanced auto-save functionality.
 
 ### Session Outputs
 
-When auto-save is enabled,that is turned on, Runme captures a complete copy of the original Markdown document along with all cell outputs generated during the notebook's execution using the “**Runme Session Outputs**”.
+When auto-save is enabled, Runme captures a complete copy of the original Markdown document along with all cell outputs generated during the notebook’s execution using the  “**Runme Session Outputs**”.
 
 ![autosave-output-session](../../static/img/Autosave-output.png)
 
 The information includes when each cell was ran, the time it took, and exit codes. Additional contextual metadata like hostname and username are also saved to the Session Outputs file. Runme also captures non-text mime types like images (base64 encoded) outside of textual output produced by terminals.
 
-see an example below:
+See an example below:
 
 ```sh {"id":"01HPGQH3SV6HM949W7RHC4P563"}
 $ terraform workspace select staging
@@ -38,20 +39,19 @@ If there are more forms you like to be added, kindly [let us know](https://githu
 
 ### Why Separate Session Outputs?
 
-You might wonder why we have chosen to create a separate Session Outputs file instead of embedding outputs directly into the markdown document. Well, here are our reasons:
+You might wonder why we have chosen to create a separate Session Outputs file instead of embedding outputs directly into the Markdown document. Well, here are our reasons:
 
 1. **Promote Generality for Collaboration**: We believe that cells, including their code and commands (inputs), should remain generic to facilitate collaboration and sharing of notebooks with others. This approach is particularly important for version control-tracked files.
 2. **Avoid Version Control Errors**: Separating files prevents accidental inclusion of outputs into version control, reducing the risk of overwriting historical artifacts from previous sessions if they were stored in the same file.
-3. **Enhance User Experience (UX)**: Session files with outputs are not directly opened in the notebook UX. After writing the output, Runme may struggle to distinguish between input and output parts of a cell. Instead, the UX will prompt you to open the original document (which requires colocation in the same folder) as a notebook or launch the markdown previewer to display the Session Outputs.
+3. **Enhance User Experience (UX)**: Session files with outputs are not directly opened in the notebook UX. After writing the output, Runme may struggle to distinguish between input and output parts of a cell. Instead, the UX will prompt you to open the original document (which requires colocation in the same folder) as a notebook or launch the Markdown previewer to display the Session Outputs.
 
-While we are contemplating the possibility of transparently opening Session Outputs files in the future, this may inevitably involve reformatting the original source file as part of the de-/serialization process.
+While we are contemplating the possibility of transparently opening Session Outputs files in the future, this may inevitably involve reformatting the original source file as part of the deserialization process.
 
 <br />
 <Infobox type="sidenote" title="Session Outputs">
 It is strongly recommended that you do not deploy the session output files to your version control. you can `.gitignore` the files to ensure that it doesn't get deployed.
 </Infobox>
 
-
 ## **How to Enable Auto-Save**
 
 - Toggle Auto-Save On/Off: On your `.md` file, you have the flexibility to easily turn the Auto-Save feature on or off. This can be done directly from the top of your Markdown (`.md`) file. A simple toggle switch allows for easy control, ensuring that you can activate or deactivate Auto-Save as per your workflow requirements.