Update docs (#1594)

Author: jmgomez

nimble-guide/docs/index.md

@@ -31,6 +31,40 @@ Nimble packages are typically hosted in Git repositories so you may be able to g
 
 
 
+## Automatic Nim Version Management
+
+Nimble can automatically download and manage Nim versions for your projects. This feature ensures that each project uses the correct Nim version without manual intervention.
+
+### How It Works
+
+When you run Nimble commands like `build` or `install`:
+
+1. **Nimble checks your project's Nim requirement** specified in the `.nimble` file (e.g., `requires "nim >= 2.0.0"`)
+2. **If a compatible Nim is not available**, Nimble automatically downloads a prebuilt binary from [nim-lang.org](https://nim-lang.org)
+3. **The downloaded Nim is cached** in `~/.nimble/nim/` and reused for future builds
+
+### Benefits
+
+- **No manual Nim installation required** - Just install Nimble and start building
+- **Per-project Nim versions** - Different projects can use different Nim versions
+- **Lock file support** - The exact Nim version can be pinned in `nimble.lock`
+- **Automatic updates** - When a project requires a newer Nim, it's downloaded automatically
+
+### Using System Nim
+
+Nimble will always try to match your system Nim version against the project's requirements. The `--useSystemNim` flag is used to bypass stricter constraints when you want to force the use of your locally installed Nim:
+
+```sh
+nimble build --useSystemNim
+```
+
+This is useful when:
+
+- You have a custom Nim build
+- You're working offline and already have Nim installed
+- You want to test with a specific Nim version not available as a binary
+
+
 ## Getting Started
 
 - If you wish to explore existing Nim packages and install some of them, follow the [using packages guide](./use-packages.md).

nimble-guide/docs/nimble-reference.md

@@ -73,4 +73,39 @@
   **Example**: `nim >= 0.10.0, jester`; with this value your package will
   depend on `nim` version 0.10.0 or greater and on any version of `jester`.
 
+#### Local Path Dependencies
+
+You can reference local packages using the `file://` protocol. This is useful for:
+
+- Monorepo setups where multiple packages live in the same repository
+- Development of interdependent packages
+- Using local forks or modifications of packages
+
+**Example**:
+```nim
+requires "file://./libs/myutil"
+requires "file://../shared/common"
+requires "file:///absolute/path/to/package"
+```
+
+Paths can be relative (resolved from the package's directory) or absolute.
+
+### Command Line Options
+
+#### `--extra-requires`
+
+Specify additional dependencies from the command line without modifying the `.nimble` file. This is useful for:
+
+- Adding optional development dependencies
+- Testing with specific package versions
+- CI/CD pipelines that need additional packages
+
+**Example**:
+```sh
+nimble build --extra-requires:"unittest2 >= 0.2.0"
+nimble install --extra-requires:"chronicles,stew"
+```
+
+Multiple packages can be specified, separated by commas.
+