feat(docs): write up a section about adding dependencies + specifiers

book/src/guide/node_modules.md

@@ -75,6 +75,93 @@ scripts.
 Skips writing, or updating the lockfile entirely. As of right now, this will
 still **read** the lockfile to inform resolution.
 
+## Adding or Removing Dependencies
+
+You can modify your current project's dependencies three different ways:
+
+1. Use the [`oro add`](../commands/add.md) command.
+2. Use the [`oro remove`](../commands/remove.md) command.
+3. Edit `package.json` manually and rerun [`oro apply`](../commands/apply.md).
+
+When any of these methods are used, orogene will update the current dependency
+tree such that the changed dependencies are reflected. This process means that
+the dependencies specified in `package-lock.kdl` won't necessarily be obeyed:
+In general, Orogene will do its best to preserve a dependency's previous
+position in the tree, but if a conflict happens, it may be moved or replaced.
+
+In order to guarantee that Orogene only accepts tree modifications on `oro
+add`/`oro remove`, you can use the [`--locked`](#locked) option.
+
+## Specifier syntax
+
+A package specifier in orogene is a string describing which package should be
+resolved. This string, in some cases (such as in the CLI) can include a name
+under which to install that dependency. Specifiers are used both through the
+`add` CLI commands, or in the value field in your dependency objects, next to
+the requested package names.
+
+### Alias
+
+Syntax: `<alias>@<specifier>`
+
+Alias specifiers work a lot like NPM specifiers, but are able to force a
+dependency to use a certain name in the `node_modules` tree.
+
+When specifying an alias for an NPM registry package, you must use the `npm:`
+prefix before the NPM specifier itself. All other specifiers can be provided
+as-is.
+
+_Examples: `underscore@npm:lodash`, `underscore@github:lodash/lodash`_
+
+### NPM
+
+Syntax: `<package-name>[@(<semver> | <tag>)]`
+
+NPM specifiers refer to "regular" NPM packages from a registry. The
+`<package-name>` can be any valid scoped or unscoped package name. If followed
+by an `@`, either a semver range or a dist-tag can be specified.
+
+When used in `package.json`, the `<package-name>` must be omitted, and it is
+recommended that only semver ranges be used.
+
+_Examples: `lodash`, `lodash@3`, `@axodotdev/oranda@1.2.3`_
+
+### Path
+
+Syntax: `<./relative/path> | <C:\absolute\path>`
+
+Path specifiers refer to the directory in the local machine where a package
+exists. They can either be relative (in which case they must be prefixed by
+`./` or `.\`), or absolute (in which case they must start with either `/` or a
+drive letter).
+
+_Examples_: `./path/to/my/proj`, `C:\src\foo`
+
+### Hosted Git
+
+Syntax: `<host>:<org>/<proj>[#(<rev> | semver:<semver>)]`
+
+Hosted git specifiers refer to packages on a handful of well-known hosted git
+platforms, and can be used as a shorthand. You may optionally provide either a
+git rev or a `semver:`-prefixed semver range following a `#` to resolve to a
+particular version, instead of the latest `HEAD`.
+
+Supported platforms: `github`, `gitlab`, `gist`, `bitbucket`.
+
+_Examples: `github:orogene/orogene`, `gist:foo/bar#deadcafe`, `gitlab:baz/quux#semver:^1.2`_
+
+### Git
+
+Syntax: `[git+]<git-url>[#(<rev> | semver:<semver>)]`
+
+Arbitrary git URLs can also be provided to Orogene. For `git://` URLs, no
+prefix is necessary, but other URL types must include a `git+` prefix. You may
+optionally provide either a git rev or a `semver:`-prefixed semver range
+following a `#` to resolve to a particular version, instead of the latest
+`HEAD`.
+
+_Examples: `git://github.com/lodash/lodash`, `git+ssh://codeberg.org/foo/bar.git#semver:^1.2.3`_
+
 ## Phantom Dependencies
 
 "Phantom dependencies" refers to a phenomenon where dependencies that weren't