docs: Update documentation for CLI command extensions and overrides

Author: tercel

README.md

@@ -407,7 +407,7 @@ Apache-2.0
 
 ## 🔗 Links
 
-- **Documentation**: [docs/index.md](docs/index.md) - Complete documentation
+- **Documentation**: [docs/index.md](docs/README.md) - Complete documentation
 - **Website**: [aipartnerup.com](https://aipartnerup.com)
 - **GitHub**: [aipartnerup/apflow](https://github.com/aipartnerup/apflow)
 - **PyPI**: [apflow](https://pypi.org/project/apflow/)

docs/guides/cli.md

@@ -259,3 +259,57 @@ apflow users stat
 ```
 
 For more details on how to develop these extensions, see the [Extending Guide](../development/extending.md#creating-cli-extensions).
+
+## Extending and Overriding CLI Commands
+
+apflow allows you to register new CLI command groups or single commands, extend existing groups, or override built-in commands and groups. This is done using the `@cli_register` decorator, with the `group` and `override=True` parameters.
+
+### Register a New Command or Group
+```python
+from apflow.cli.decorators import cli_register
+
+@cli_register(name="my-group", help="My command group")
+class MyGroup:
+    def foo(self):
+        print("foo")
+    def bar(self):
+        print("bar")
+```
+
+### Add a Subcommand to an Existing Group
+```python
+@cli_register(group="my-group", name="baz", help="Baz command")
+def baz():
+    print("baz")
+```
+
+### Override an Existing Command or Group
+
+```python
+@cli_register(name="my-group", override=True)
+class NewMyGroup:
+    ...
+
+@cli_register(group="my-group", name="foo", override=True)
+def new_foo():
+    print("new foo")
+```
+
+**Override a built-in command (e.g., 'run'):**
+```python
+from apflow.cli.decorators import cli_register
+
+@cli_register(name="run", override=True, help="Override built-in run command")
+def my_run():
+    print("This is my custom run command!")
+```
+Now, running `apflow run` will execute your custom logic instead of the built-in command.
+
+### Core Extension Override
+
+apflow also supports custom extensions for executors, hooks, storage backends, and more. You can register your own or override built-in extensions by passing `override=True` when registering.
+
+**Best Practices:**
+- Use `override=True` only when you want to replace an existing command or extension.
+- Keep extension logic simple and well-documented.
+- Test your extensions thoroughly.

docs/guides/extensions.md

@@ -0,0 +1,24 @@
+# Extensions in apflow
+
+apflow supports a powerful extension system for both CLI commands and core functionality. You can add your own extensions or override existing ones, making it easy to customize and adapt apflow to your needs.
+
+## CLI Extensions: Custom Commands and Overriding
+
+You can register new CLI command groups or single commands using the `@cli_register` decorator. You can also extend or override existing commands and groups by specifying the `group` and `override=True` parameters.
+
+For detailed usage and examples, see the [CLI Guide](./cli.md) and [Library Usage Guide](./library-usage.md).
+
+## Core Extensions: Custom and Override
+
+apflow also supports custom extensions for executors, hooks, storage backends, and more. You can register your own or override built-in extensions by passing `override=True` when registering.
+
+For how to override executors and other extensions, see the [API Quick Reference](../api/quick-reference.md) and [Python API Reference](../api/python.md).
+
+For more details, see the [Extending Guide](../development/extending.md).
+
+For more details, see the [Extending Guide](../development/extending.md).
+
+## Best Practices
+- Use `override=True` only when you want to replace an existing command or extension.
+- Keep extension logic simple and well-documented.
+- Test your extensions thoroughly.

docs/guides/library-usage.md

@@ -406,6 +406,64 @@ This means your custom middleware runs **after** the default middleware, so it c
 5. **Test middleware** thoroughly as it affects all requests
 6. **Use type hints** for better code clarity
 
+## Extending and Overriding CLI Commands and Extensions
+
+apflow supports advanced extensibility for both CLI commands and core extensions. You can add your own commands, extend existing groups, or override built-in commands and extensions using simple decorators and parameters.
+
+### CLI Command Extension and Override
+
+
+You can register new CLI command groups or single commands using the `@cli_register` decorator. To extend an existing group, use the `group` parameter. To override an existing command or group, set `override=True`.
+
+**Register a new command group:**
+```python
+from apflow.cli.decorators import cli_register
+
+@cli_register(name="my-group", help="My command group")
+class MyGroup:
+    def foo(self):
+        print("foo")
+    def bar(self):
+        print("bar")
+```
+
+**Add a subcommand to an existing group:**
+```python
+@cli_register(group="my-group", name="baz", help="Baz command")
+def baz():
+    print("baz")
+```
+
+**Override an existing command or group:**
+```python
+@cli_register(name="my-group", override=True)
+class NewMyGroup:
+    ...
+
+@cli_register(group="my-group", name="foo", override=True)
+def new_foo():
+    print("new foo")
+```
+
+**Override a built-in command (e.g., 'run'):**
+```python
+from apflow.cli.decorators import cli_register
+
+@cli_register(name="run", override=True, help="Override built-in run command")
+def my_run():
+    print("This is my custom run command!")
+```
+Now, running `apflow run` will execute your custom logic instead of the built-in command.
+
+### Core Extension Override
+
+apflow also supports custom extensions for executors, hooks, storage backends, and more. You can register your own or override built-in extensions by passing `override=True` when registering.
+
+**Best Practices:**
+- Use `override=True` only when you want to replace an existing command or extension.
+- Keep extension logic simple and well-documented.
+- Test your extensions thoroughly.
+
 ## Quick Reference: What main.py Does
 
 For reference, here's what `apflow.api.main.main()` and `create_runnable_app()` do: