docs: add package.json config source and priority system documentation

- Add "Project Configuration (package.json)" section to configuration.md
- Document allowed fields: shortCode, clientId, mrtProject, mrtOrigin, accountManagerHost
- Explain security rationale for excluding sensitive fields
- Update resolution priority list to include package.json as lowest priority
- Document numeric priority system in extending.md
- Add priority table showing ranges (< 0, 0, 1-999, 1000)
- Add example showing how to set priority on custom ConfigSource

Author: clavery

docs/guide/configuration.md

@@ -148,18 +148,56 @@ For multi-instance configurations, each config object also supports:
 | `name` | Instance name for selection with `-i`/`--instance` |
 | `active` | Set to `true` to use this config by default |
 
+## Project Configuration (package.json)
+
+You can store project-level defaults in your `package.json` file under the `b2c` key. This is useful for settings that are shared across your entire project and safe to commit to version control.
+
+```json
+{
+  "name": "my-storefront",
+  "version": "1.0.0",
+  "b2c": {
+    "shortCode": "abc123",
+    "clientId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+    "mrtProject": "my-project",
+    "accountManagerHost": "account.demandware.com"
+  }
+}
+```
+
+### Allowed Fields
+
+Only non-sensitive, project-level fields can be configured in `package.json`:
+
+| Field | Description |
+|-------|-------------|
+| `shortCode` | SCAPI short code |
+| `clientId` | OAuth client ID (for implicit login discovery) |
+| `mrtProject` | MRT project slug |
+| `mrtOrigin` | MRT API origin URL override |
+| `accountManagerHost` | Account Manager hostname for OAuth |
+
+::: warning Security Note
+Sensitive fields like `hostname`, `password`, `clientSecret`, `username`, and `mrtApiKey` are intentionally **not** supported in `package.json`. These should be configured via `dw.json` (which should be in `.gitignore`), environment variables, or secure credential stores.
+:::
+
+::: tip Lowest Priority
+`package.json` has the lowest priority of all configuration sources. Values from `dw.json`, environment variables, or CLI flags will always override `package.json` settings. This makes it ideal for project defaults that can be overridden per-environment.
+:::
+
 ### Resolution Priority
 
 Configuration is resolved with the following precedence (highest to lowest):
 
 1. **CLI flags and environment variables** - Explicit values always take priority
-2. **Plugin sources (high priority)** - Custom sources with `priority: 'before'`
-3. **dw.json** - Project configuration file
-4. **~/.mobify** - Home directory file (for MRT API key only)
-5. **Plugin sources (low priority)** - Custom sources with `priority: 'after'`
+2. **Plugin sources (high priority)** - Custom sources with `priority: 'before'` (or priority < 0)
+3. **dw.json** - Project configuration file (priority 0)
+4. **~/.mobify** - Home directory file for MRT API key (priority 0)
+5. **Plugin sources (low priority)** - Custom sources with `priority: 'after'` (or priority 1-999)
+6. **package.json** - Project-level defaults (priority 1000, lowest)
 
 ::: tip Extending Configuration
-Plugins can add custom configuration sources like secret managers or environment-specific files. See [Extending the CLI](./extending) for details.
+Plugins can add custom configuration sources like secret managers or environment-specific files. Plugins can use numeric priorities for fine-grained control over ordering. See [Extending the CLI](./extending) for details.
 :::
 
 ### Credential Grouping

docs/guide/extending.md

@@ -58,19 +58,48 @@ This hook is called during command initialization, after CLI flags are parsed bu
 | Property | Type | Description |
 |----------|------|-------------|
 | `sources` | `ConfigSource[]` | Config sources to add to resolution |
-| `priority` | `'before' \| 'after'` | Where to insert relative to defaults (default: `'after'`) |
+| `priority` | `'before' \| 'after' \| number` | Priority for sources (see below). Default: `'after'` |
+
+::: tip Numeric Priorities
+String values map to numeric priorities: `'before'` → -1, `'after'` → 10. You can also use any numeric value directly for fine-grained control. Lower numbers = higher priority.
+:::
 
 ### Priority Ordering
 
+Configuration sources use a numeric priority system where **lower numbers = higher priority**:
+
+| Priority | Description | Example |
+|----------|-------------|---------|
+| < 0 | Override built-in sources | `'before'` maps to -1 |
+| 0 | Built-in sources | `dw.json`, `~/.mobify` |
+| 1-999 | After built-in sources | `'after'` maps to 10 |
+| 1000 | Lowest priority | `package.json` |
+
 Configuration is resolved with the following precedence:
 
 1. **CLI flags and environment variables** - Always highest priority
-2. **Plugin sources with `priority: 'before'`** - Override dw.json defaults
-3. **Default sources** - `dw.json` and `~/.mobify`
-4. **Plugin sources with `priority: 'after'`** - Fill gaps left by defaults
+2. **Plugin sources with `priority: 'before'` (or < 0)** - Override dw.json defaults
+3. **Default sources** - `dw.json` and `~/.mobify` (priority 0)
+4. **Plugin sources with `priority: 'after'` (or 1-999)** - Fill gaps left by defaults
+5. **package.json** - Project-level defaults (priority 1000)
 
 Each source fills in missing values - it doesn't override values from higher-priority sources.
 
+::: tip Custom ConfigSource Priority
+When implementing a custom `ConfigSource`, you can set the `priority` property directly on your class:
+
+```typescript
+export class MyCustomSource implements ConfigSource {
+  readonly name = 'my-custom-source';
+  readonly priority = 5; // Between 'before' (-1) and 'after' (10)
+
+  load(options: ResolveConfigOptions): ConfigLoadResult | undefined {
+    // ...
+  }
+}
+```
+:::
+
 ::: warning Credential Grouping
 OAuth credentials (`clientId`/`clientSecret`) and Basic auth credentials (`username`/`password`) are treated as atomic groups. If any field in a group is already set by a higher-priority source, all fields in that group from your source will be ignored. Ensure your source provides complete credential pairs, or that higher-priority sources don't partially define the same credentials.
 :::