docs: improve README.md

README.md

@@ -1,58 +1,66 @@
 # ORAS Go library
 
+[![Build Status](https://github.com/oras-project/oras-go/actions/workflows/build.yml/badge.svg?event=push&branch=main)](https://github.com/oras-project/oras-go/actions/workflows/build.yml?query=workflow%3Abuild+event%3Apush+branch%3Amain)
+[![codecov](https://codecov.io/gh/oras-project/oras-go/branch/main/graph/badge.svg)](https://codecov.io/gh/oras-project/oras-go)
+[![Go Report Card](https://goreportcard.com/badge/oras.land/oras-go/v2)](https://goreportcard.com/report/oras.land/oras-go/v2)
+[![Go Reference](https://pkg.go.dev/badge/oras.land/oras-go/v2.svg)](https://pkg.go.dev/oras.land/oras-go/v2)
+
 <p align="left">
-<a href="https://oras.land/"><img src="https://oras.land/img/oras.svg" alt="banner" width="100px"></a>
+<a href="https://oras.land/"><img src="https://oras.land/img/oras.svg" alt="ORAS logo" width="100px"></a>
 </p>
 
-## Project status
+`oras-go` is a Go library for managing OCI artifacts, compliant with the [OCI Image Format Specification](https://github.com/opencontainers/image-spec) and the [OCI Distribution Specification](https://github.com/opencontainers/distribution-spec). It provides unified APIs for pushing, pulling, and managing artifacts across OCI-compliant registries, local file systems, and in-memory stores.
 
-### Versioning
+> [!Note]
+> The `main` branch follows [Go's Security Policy](https://github.com/golang/go/security/policy) and supports the two latest versions of Go (currently `1.23` and `1.24`).
 
-The ORAS Go library follows [Semantic Versioning](https://semver.org/), where breaking changes are reserved for MAJOR releases, and MINOR and PATCH releases must be 100% backwards compatible.
+## Getting Started
 
-### v2: stable
+### Concepts
 
-[![Build Status](https://github.com/oras-project/oras-go/actions/workflows/build.yml/badge.svg?event=push&branch=main)](https://github.com/oras-project/oras-go/actions/workflows/build.yml?query=workflow%3Abuild+event%3Apush+branch%3Amain)
-[![codecov](https://codecov.io/gh/oras-project/oras-go/branch/main/graph/badge.svg)](https://codecov.io/gh/oras-project/oras-go)
-[![Go Report Card](https://goreportcard.com/badge/oras.land/oras-go/v2)](https://goreportcard.com/report/oras.land/oras-go/v2)
-[![Go Reference](https://pkg.go.dev/badge/oras.land/oras-go/v2.svg)](https://pkg.go.dev/oras.land/oras-go/v2)
+Gain insights into the fundamental concepts:
 
-The version `2` is actively developed in the [`main`](https://github.com/oras-project/oras-go/tree/main) branch with all new features.
+- [Modeling Artifacts](docs/Modeling-Artifacts.md)
+- [Targets and Content Stores](docs/Targets.md)
 
-> [!Note]
-> The `main` branch follows [Go's Security Policy](https://github.com/golang/go/security/policy) and supports the two latest versions of Go (currently `1.23` and `1.24`).
+### Quickstart
+
+Follow the step-by-step tutorial to use `oras-go` v2:
+
+- [Quickstart: Managing OCI Artifacts with `oras-go` v2](docs/tutorial/quickstart.md)
+
+### Examples
 
-Examples for common use cases can be found below:
+Check out sample code for common use cases:
 
-- [Copy examples](https://pkg.go.dev/oras.land/oras-go/v2#pkg-examples)
-- [Registry interaction examples](https://pkg.go.dev/oras.land/oras-go/v2/registry#pkg-examples)
-- [Repository interaction examples](https://pkg.go.dev/oras.land/oras-go/v2/registry/remote#pkg-examples)
-- [Authentication examples](https://pkg.go.dev/oras.land/oras-go/v2/registry/remote/auth#pkg-examples)
+- [Artifact copying](https://pkg.go.dev/oras.land/oras-go/v2#pkg-examples)
+- [Registry operations](https://pkg.go.dev/oras.land/oras-go/v2/registry#pkg-examples)
+- [Repository operations](https://pkg.go.dev/oras.land/oras-go/v2/registry/remote#pkg-examples)
+- [Authentication](https://pkg.go.dev/oras.land/oras-go/v2/registry/remote/auth#pkg-examples)
+- [Credentials management](https://pkg.go.dev/oras.land/oras-go/v2/registry/remote/credentials#pkg-examples)
 
-If you are seeking latest changes, you should use the [`main`](https://github.com/oras-project/oras-go/tree/main) branch (or a specific commit hash) over a tagged version when including the ORAS Go library in your project's `go.mod`.
-The Go Reference for the `main` branch is available [here](https://pkg.go.dev/oras.land/oras-go/v2@main).
+Find more API examples at [pkg.go.dev](https://pkg.go.dev/oras.land/oras-go/v2).
 
-To migrate from `v1` to `v2`, see [MIGRATION_GUIDE.md](./MIGRATION_GUIDE.md).
 
-### v1: stable
+## Versioning
+
+This project follows [Semantic Versioning](https://semver.org/) (`MAJOR`.`MINOR`.`PATCH`), with `MAJOR` for breaking changes, `MINOR` for backward-compatible features, and `PATCH` for backward-compatible fixes.
+
+## Previous Major Versions
+
+### v1 (maintenance)
 
 [![Build Status](https://github.com/oras-project/oras-go/actions/workflows/build.yml/badge.svg?event=push&branch=v1)](https://github.com/oras-project/oras-go/actions/workflows/build.yml?query=workflow%3Abuild+event%3Apush+branch%3Av1)
 [![Go Report Card](https://goreportcard.com/badge/oras.land/oras-go)](https://goreportcard.com/report/oras.land/oras-go)
 [![Go Reference](https://pkg.go.dev/badge/oras.land/oras-go.svg)](https://pkg.go.dev/oras.land/oras-go)
 
-As there are various stable projects depending on the ORAS Go library `v1`, the
-[`v1`](https://github.com/oras-project/oras-go/tree/v1) branch
-is maintained for API stability, dependency updates, and security patches.
-All `v1.*` releases are based upon this branch.
-
-Since `v1` is in a maintenance state, you are highly encouraged
-to use releases with major version `2` for new features.
-
-## Docs
+The [`v1`](https://github.com/oras-project/oras-go/tree/v1) branch is maintained for dependency updates and security fixes only. All feature development happens in the [`main`](https://github.com/oras-project/oras-go/tree/main) branch.
 
-- [oras.land/client_libraries/go](https://oras.land/docs/Client_Libraries/go): Documentation for the ORAS Go library
-- [Reviewing guide](https://github.com/oras-project/community/blob/main/REVIEWING.md): All reviewers must read the reviewing guide and agree to follow the project review guidelines.
+To migrate from `v1` to `v2`, see [MIGRATION_GUIDE.md](MIGRATION_GUIDE.md).
 
-## Code of Conduct
+## Community
 
-This project has adopted the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md). See [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for further details.
+- Code of Conduct: [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
+- Security Policy: [SECURITY.md](SECURITY.md)
+- Reviewing Guide: [Reviewing Guide](https://github.com/oras-project/community/blob/main/REVIEWING.md)
+- Slack: [`#oras`](https://cloud-native.slack.com/archives/CJ1KHJM5Z) channel on CNCF Slack

docs/README.md

@@ -0,0 +1,16 @@
+# `oras-go` v2 Documentation
+
+This directory contains the fundamentals and a quickstart tutorial for `oras-go` v2.
+
+## Fundamentals
+
+It is highly recommended to read the following documentation in order:
+
+- [Modeling Artifacts](./Modeling-Artifacts.md)
+- [Targets and Content Stores in `oras-go` v2](./Targets.md)
+
+## Quickstart Tutorial
+
+- [Quickstart: Managing OCI Artifacts with `oras-go` v2](./tutorial/quickstart.md)
+
+For more information about the ORAS project, visit the [ORAS website](https://oras.land/).

docs/Targets.md

@@ -122,6 +122,23 @@ TagBar>"Tag: bar"]-.->M0
 TagV1>"Tag: v1"]-.->M0
 ```
 
+A descriptor can have multiple tags, but each tag is associated with only one descriptor. Reusing a tag for a different descriptor removes its previous association.
+
+If the tag `"bar"` is reused on another manifest `m1`, the graph would update as follows:
+
+```mermaid
+graph TD;
+
+M0["Manifest m0"]--config-->Blob0["Blob b0"]
+M0--layers-->Blob1["Blob b1"]
+M0--layers-->Blob2["Blob b2"]
+M1["Manifest m1"]
+
+TagFoo>"Tag: foo"]-.->M0
+TagV1>"Tag: v1"]-.->M0
+TagBar>"Tag: bar"]-.->M1
+```
+
 ### GraphTarget
 
 The [`GraphTarget`](https://pkg.go.dev/oras.land/oras-go/v2#GraphTarget) interface combines the capabilities of [`GraphStorage`](#graphstorage) and [`Target`](#target). It provides the following functions: