iterative · aguschin · Dec 8, 2022 · Nov 23, 2022 · Nov 24, 2022 · Nov 24, 2022
diff --git a/content/docs/gto/dvc.md b/content/docs/gto/dvc.md
diff --git a/content/docs/gto/get-started.md b/content/docs/gto/get-started.md
@@ -89,7 +89,7 @@ during registrations and promotions. The benefit of these Git-native mechanism
 is that you can act upon GTO operations in any Git-based system downstream, for
 example automating model deployments with CI/CD.
 
-[tags]: /doc/gto/user-guide#git-tags-message-format
+[tags]: /doc/gto/user-guide#git-tags-format
 
 <details>
 
@@ -160,9 +160,9 @@ page.
 Thanks for completing this Get Started!
 
 - Learn how to
-  [specify important artifact's metainformation](/doc/gto/user-guide#annotations-in-artifactsyaml)
-  like `path`, `type` and `description` in the Artifact registry.
-- Learn more about [acting in CI/CD](/doc/gto/user-guide#acting-in-ci-cd) upon
+  [get your artifacts](/doc/gto/user-guide#getting-artifacts-downstream) when
+  you need them (e.g. get the latest version or the version in specific stage).
+- Learn more about [acting in CI/CD](/doc/gto/user-guide#acting-in-cicd) upon
   version registrations and stage assignments.
 - Reach us out in [GH issues](https://github.com/iterative/gto/issues) or in
   [Discord](https://discord.com/invite/dvwXA2N) to get your questions answered!
diff --git a/content/docs/gto/mlem.md b/content/docs/gto/mlem.md
diff --git a/content/docs/gto/user-guide/dvc.md b/content/docs/gto/user-guide/dvc.md
@@ -0,0 +1,144 @@
+# GTO with DVC
+
+In many ML projects, data isn't stored in a Git repository and needs to be
+downloaded from external sources. [DVC](https://dvc.org) is a common way to
+store binaries for the artifacts registered with GTO.
+
+<details>
+
+### Learn about different approaches to this
+
+1. You can commit artifacts to Git repo. If they aren't small enough, this is
+   not recommended. To bypass this limitation, you can use
+   [Git-lfs](https://git-lfs.github.com).
+2. You can version binaries with [DVC](https://dvc.org/) and commit pointers to
+   them to the repo. This is the recommended approach for large files.
+3. You can version binaries manually somewhere, specifying URL to them as `path`
+   in `artifacts.yaml`. This can be done, if your artifacts are already
+   versioned by some external system.
+
+</details>
+
+If you are new to DVC, you should start with
+[DVC Get Started](https://dvc.org/doc/start) first, and then come back to this
+Guide.
+
+<!-- ```
+
+dvc init --no-scm dvc remote add az azure://container-name export
+AZURE_STORAGE_CONNECTION_STRING='YOUR_CONNECTION_STRING'
+
+dvc import-url --no-download azure://container-name/data.parquet
+
+``` -->
+
+## Tracking an artifact with DVC
+
+First, we need to start tracking artifact with DVC. If you produce this artifact
+in DVC Pipelines, it's done automatically.
+
+If the artifact is located inside your Git repo, you can use `dvc add`:
+
+```cli
+$ dvc add model.pkl
+$ git add model.pkl.dvc
+```
+
+If the artifact is located in some external storage, we can use `dvc import-url`
+to still keep metainformation about it in the repo (use `--no-download` to skip
+downloading it):
+
+```cli
+$ dvc import-url --no-download s3://container/model.pkl
+$ git add model.pkl.dvc
+```
+
+## Annotating DVC-tracked artifacts
+
+Once the artifact is tracked with DVC within your repo, we can annotate it with
+GTO:
-Once the artifact is tracked with DVC within your repo, we can annotate it with
-GTO:
+Once the artifact is
+[tracked with DVC](https://dvc.org/doc/command-reference/add) within your repo,
+`gto annotate` it:
-Once the artifact is tracked with DVC within your repo, we can annotate it with
-GTO:
+Once the artifact is
+[tracked with DVC](https://dvc.org/doc/command-reference/add) within your repo,
+`gto annotate` it:
+
+```cli
+$ gto annotate model --path model.pkl
+```
+
+This will modify `artifacts.yaml`, adding:
+
+```yaml
+model:
+  path: model.pkl
+```
+
+Now you should commit changes to Git, and you can register versions and assign
+stages referencing the new commit.
+
+```cli
+$ git add artifacts.yaml
+$ git commit -m "version artifact binaries with DVC and annotate it with GTO"
+$ git push
+```
+
+Now your changes is live in your Git repo and you can download your artifact to
+use it 🙌
+
+## Downloading artifacts
+
+When you want to download GTO artifact which binaries are stored with DVC, you
+need to use `dvc get` or `dvc import` command:
+
+```cli
+$ dvc get $REPO $ARTIFACT_PATH --rev $REVISION -o $OUTPUT_PATH
+```
+
+Check out [User Guide](/doc/gto/user-guide#getting-artifacts-downstream) to
+learn how to find out `ARTIFACT_PATH` and `REVISION`.
+
+<details>
+
+### Example: downloading from outside the repo
+
+If you need to download the latest version of `model`, that would be:
+
+```cli
+$ REVISION=$(gto show --repo $REPO model@greatest --ref)
+$ ARTIFACT_PATH=$(gto describe --repo $REPO $ARTIFACT --rev $REVISION --path)
+$ dvc get $REPO $ARTIFACT --rev $REVISION -o $ARTIFACT_PATH
+```
+
+</details>
+
+<details>
+
+### Example: downloading in CI
+
+If you need to download an artifact from the same repo, that would be a bit
+simpler (taking GH Actions as an example):
+
+```cli
+$ ARTIFACT_PATH=$(gto describe model --rev $GITHUB_REF --path)
+$ dvc pull $ARTIFACT_PATH
+```
+
+</details>
+
+<!--
+Refer to DVC install guide and Get Started to learn DVC first. If you're already
+familiar with DVC, let's set it up for GTO repo (use your remote storage instead
+of `s3://mybucket/myrepo`):
+
+```cli
+$ dvc init
+$ dvc remote add myremote -d s3://mybucket/myrepo
+$ git add .dvc/config
+```
+
+##
+
+If you want to version your artifact with DVC, you need to add it to DVC first
+(skip this step if you already have DVC-tracked artifacts):
+
+```cli
+$ dvc add path/to/artifact
+$ dvc push
+$ git add
+``` -->
diff --git a/content/docs/gto/user-guide.md → content/docs/gto/user-guide/index.md b/content/docs/gto/user-guide.md → content/docs/gto/user-guide/index.md
@@ -2,11 +2,11 @@
 
 GTO helps you build an Artifact Registry out of your Git repository. It creates
 annotated [Git tags](https://git-scm.com/book/en/v2/Git-Basics-Tagging) with a
-[special format](#git-tag-message-format) in their message, and manages an
+[special format](#git-tags-format) in their message, and manages an
 `artifacts.yaml` file. Since committing large files to Git is not a good
-practice, you should consider not committing your artifacts to Git. Instead, use
-[DVC](https://dvc.org/doc), Git-lfs, or any method commit pointers to the binary
-files instead.
+practice, you should consider not committing your artifacts to Git. Instead,
+[use DVC](/doc/gto/user-guide/dvc), Git-lfs, or any method to commit pointers to
+the binary files instead.
 
 ## Annotations in artifacts.yaml
 
@@ -17,19 +17,62 @@ itself doesn't contain path to the artifact, type of it (it could be `model` or
 [in a CI/CD system](#acting-in-ci-cd) downstream. But for more advanced cases,
 we should codify them in the registry itself.
 
-To keep this metainformation, GTO uses `artifacts.yaml` file. Commands like
+To keep this metadata, GTO uses `artifacts.yaml` file. Commands like
 `gto annotate` and `gto remove` are used to modify it, while `gto describe`
 helps get them when they're needed.
 
-If you would like to see an example of `artifacts.yaml`, check out the
+<admon type="tip">
+
+An example of `artifacts.yaml` can be found in
 [example-gto](https://github.com/iterative/example-gto/blob/main/artifacts.yaml)
 repo.
 
+</admon>
+
+## Getting artifacts in systems downstream
+
+You may need to get a specific artifact version to a certain environment, most
+likely the latest one or the one currently assigned to the stage. Use `gto show`
+to find the [Git reference] (tag) you need (note that
+[CI platforms](#acting-in-ci-cd) may expose it for you, e.g. the `GITHUB_REF`
+[env var in GitHub Actions]):
+
+[git reference]: https://git-scm.com/book/en/v2/Git-Internals-Git-References
+[env var in github actions]:
+  https://docs.github.com/en/actions/learn-github-actions/environment-variables
+
+<admon type="tip">
+
+GTO doesn't provide a way to deliver the artifacts, but you can [use DVC] or
+[employ MLEM] for that.
+
+[use dvc]: /doc/gto/user-guide/dvc
+[employ mlem]: /doc/gto/user-guide/mlem
+
+</admon>
+
+```cli
+# getting the Git reference for the latest version
+$ gto show churn@greatest --ref
+[email protected]
+
+$ gto show churn#prod --ref  # by assigned stage
+[email protected]
+```
+
+You may need the artifact's file path. If
+[annotated](#annotations-in-artifactsyaml), it can be discovered with
+`gto describe`:
+
+```cli
+$ gto describe churn --rev [email protected] --path
+models/churn.pkl
+```
+
 ## Acting in CI/CD
 
-Once Git tags are pushed, you can start acting in systems downstream. A popular
-options is to use CI/CD (triggered when Git tags are pushed). For general
-details, check out something like
+A popular deployment option is to use CI/CD (triggered when Git tags are
+pushed). For general details, check out something like
 [GitHub Actions](https://github.com/features/actions),
 [GitLab CI/CD](https://docs.gitlab.com/ee/ci/) or
 [Circle CI](https://circleci.com).
@@ -79,7 +122,7 @@ Alternatively, you can use environment variables (note the `GTO_` prefix)
 $ GTO_EMOJIS=false gto show
 ```
 
-## Git tag message format
+## Git tags format
 
 <admon type="tip">