docs(app-namespace): add documentation for app namespace (#499)

Author: badmonster0

docs/docs/core/cli.mdx

@@ -41,7 +41,7 @@ You may also provide a `cocoindex_cmd` argument to the `main_fn` decorator to ch
 
 ### Explicitly CLI Invoke
 
-An alterntive way is to use `cocoindex.cli.cli` (with type [`click.Group`](https://click.palletsprojects.com/en/stable/api/#click.Group)).
+An alternative way is to use `cocoindex.cli.cli` (with type [`click.Group`](https://click.palletsprojects.com/en/stable/api/#click.Group)).
 For example, you may invoke the CLI explicitly with additional arguments:
 
 <Tabs>
@@ -60,7 +60,7 @@ The following subcommands are available:
 
 | Subcommand | Description |
 | ---------- | ----------- |
-| `ls` | List all flows. |
+| `ls` | List all flows present in the current process. Or list all persisted flows under the current app namespace if `--all` is specified. |
 | `show` | Show the spec for a specific flow. |
 | `setup` | Check and apply backend setup changes for flows, including the internal and target storage (to export). |
 | `drop` | Drop the backend setup for specified flows. |

docs/docs/core/initialization.mdx

@@ -83,8 +83,19 @@ if __name__ == "__main__":
 
 `cocoindex.Settings` is used to configure the CocoIndex library.  It's a dataclass that contains the following fields:
 
+*   `app_namespace` (type: `str`, required): The namespace of the application.
 *   `database` (type: `DatabaseConnectionSpec`, required): The connection to the Postgres database.
 
+### App Namespace
+
+The `app_namespace` field helps organize flows across different environments (e.g., testing, production) or teams. When set, it prefixes flow names with the namespace.
+
+For example, if the namespace is "Staging", for a flow with name specified as `Flow1` in code, the full name of the flow will be `Staging.Flow1`.
+
+If not set, all flows are in a default unnamed namespace.
+
+You can also control it by the `COCOINDEX_APP_NAMESPACE` environment variable.
+
 ### DatabaseConnectionSpec
 
 `DatabaseConnectionSpec` configures the connection to a database. Only Postgres is supported for now. It has the following fields:
@@ -116,6 +127,7 @@ Each setting field has a corresponding environment variable:
 
 | environment variable | corresponding field in `Settings` | required? |
 |---------------------|-------------------|----------|
+| `COCOINDEX_APP_NAMESPACE` | `app_namespace` | No |
 | `COCOINDEX_DATABASE_URL` | `database.url` | Yes |
 | `COCOINDEX_DATABASE_USER` | `database.user` | No |
 | `COCOINDEX_DATABASE_PASSWORD` | `database.password` | No |

python/cocoindex/cli.py

@@ -16,7 +16,7 @@ def cli():
 @cli.command()
 @click.option(
     "-a", "--all", "show_all", is_flag=True, show_default=True, default=False,
-    help="Also show all flows with persisted setup, even if not defined in the current process.")
+    help="Also show all flows with persisted setup under the current app namespace, even if not defined in the current process.")
 def ls(show_all: bool):
     """
     List all flows.