From 27519db79e3f29af272a6bf78fbc0580e6cc2143 Mon Sep 17 00:00:00 2001
From: Hayden Spitzley <105455169+hspitzley-czi@users.noreply.github.com>
Date: Tue, 23 Jan 2024 15:29:25 -0700
Subject: [PATCH] chore: clarify scope of configs in docs (#2976)

---
 docs/{features => commands}/config.md |  8 +++++---
 docs/commands/index.md                | 14 ++++++++++++++
 docs/features/index.md                | 13 -------------
 3 files changed, 19 insertions(+), 16 deletions(-)
 rename docs/{features => commands}/config.md (75%)
 create mode 100644 docs/commands/index.md
 delete mode 100644 docs/features/index.md

diff --git a/docs/features/config.md b/docs/commands/config.md
similarity index 75%
rename from docs/features/config.md
rename to docs/commands/config.md
index 357e989987..3ded9b68bc 100644
--- a/docs/features/config.md
+++ b/docs/commands/config.md
@@ -1,5 +1,5 @@
 ---
-parent: Features
+parent: Commands
 layout: default
 has_toc: true
 ---
@@ -10,9 +10,11 @@ One of the features of Happy allows you to manage application configuration valu
 
 See `happy config -h` for usage information.
 
-## Hierarchy of Configs
+## Scope & Hierarchy of Configs
 
-App configs are defined hierarchically where configs can be set at the environment level or at the stack level. Every stack inherits the configs of its parent environment and can be overridden at the stack level. For example, if you have an environment called `rdev` and a stack called `foo`, the `foo` stack will inherit all the configs of the `rdev` environment. When a config with the same key is defined in both the environment and the stack, the stack's config value will take precedence.
+App configs are scoped to an app and environment (and sometimes a stack, see below). This uses the value of `app` from your config.json file and the value passed to the `--env` flag (or the default environment if no `--env` flag is passed). This means that you can have different configs for different environments of the same app, and configs for different apps will not conflict with each other (even when the apps are deployed to the same "happy-env" (as defined by the `happy-env-eks` Terraform module)).
+
+App configs are defined hierarchically where configs can be set at the environment level or at the stack level for your app. Every stack inherits the configs of its parent environment and can be overridden at the stack level. For example, if you have an environment called `rdev` and a stack called `foo`, the `foo` stack will inherit all the configs of the `rdev` environment. When a config with the same key is defined in both the environment and the stack, the stack's config value will take precedence.
 
 ## V1
 
diff --git a/docs/commands/index.md b/docs/commands/index.md
new file mode 100644
index 0000000000..63752e8a7a
--- /dev/null
+++ b/docs/commands/index.md
@@ -0,0 +1,14 @@
+---
+layout: default
+title: Commands
+has_children: true
+nav_order: 6
+---
+
+# Commands
+
+Happy has a number of commands that you can use to manage your application. You can see a list of all the commands by running `happy -h`. You can also get help for a specific command by running `happy <COMMAND> -h`.
+
+For each command, the `.happy/config.json` file is used to determine which app to run the command against. If you do not specify an environment with the `--env` flag, the default environment is used. You can set the default environment by setting the `default_env` field in your `.happy/config.json` file.
+
+
diff --git a/docs/features/index.md b/docs/features/index.md
deleted file mode 100644
index 1e9709f3d5..0000000000
--- a/docs/features/index.md
+++ /dev/null
@@ -1,13 +0,0 @@
----
-layout: default
-title: Features
-has_children: true
-nav_order: 6
----
-
-# Features
-
-
-
-
-